X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2b5f62a0b2db198609b45dec622a018dae37008e..1722a3f626f7b29b42a22fc6329ce12fb5e8ed90:/src/png/libpng.3 diff --git a/src/png/libpng.3 b/src/png/libpng.3 index c9e96ab6a4..0d4d82958f 100644 --- a/src/png/libpng.3 +++ b/src/png/libpng.3 @@ -1,6 +1,6 @@ -.TH LIBPNG 3 "September 18, 2002" +.TH LIBPNG 3 "September 12, 2004" .SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 +libpng \- Portable Network Graphics (PNG) Reference Library 1.2.7 .SH SYNOPSIS \fI\fB @@ -100,10 +100,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBpng_uint_32 png_get_asm_flags (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - \fBpng_byte png_get_bit_depth (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP \fI\fB @@ -196,18 +192,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBpng_byte png_get_mmx_bitdepth_threshold (png_structp \fIpng_ptr\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_mmx_flagmask (int \fP\fIflag_select\fP\fB, int \fI*compilerID\fP\fB);\fP - -\fI\fB - -\fBpng_uint_32 png_get_mmx_rowbytes_threshold (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 @@ -282,10 +266,18 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB +\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + \fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP \fI\fB +\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + \fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP \fI\fB @@ -342,10 +334,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBpng_voidp png_malloc_warn (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP - -\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 @@ -362,10 +350,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBint png_mmx_support \fI(void\fP\fB);\fP - -\fI\fB - \fBDEPRECATED: void png_permit_empty_plte (png_structp \fP\fIpng_ptr\fP\fB, int \fIempty_plte_permitted\fP\fB);\fP \fI\fB @@ -418,7 +402,11 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBpng_set_asm_flags (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIasm_flags\fP\fB);\fP +\fB#if \fI!defined(PNG_1_0_X) + +\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP + +\fI\fB#endif \fI\fB @@ -550,10 +538,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBpng_set_mmx_thresholds (png_structp \fP\fIpng_ptr\fP\fB, png_byte \fP\fImmx_bitdepth_threshold\fP\fB, png_uint_32 \fImmx_rowbytes_threshold\fP\fB);\fP - -\fI\fB - \fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP \fI\fB @@ -646,12 +630,6 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB -\fBvoid png_set_strip_error_numbers (png_structp \fIpng_ptr, - -\fBpng_uint_32 \fIstrip_mode\fP\fB);\fP - -\fI\fB - \fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP \fI\fB @@ -688,6 +666,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB +\fBvoid png_set_user_limits (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIuser_width_max\fP\fB, png_uint_32 \fIuser_height_max\fP\fB);\fP + +\fI\fB + \fBvoid png_set_user_transform_info (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_transform_ptr\fP\fB, int \fP\fIuser_transform_depth\fP\fB, int \fIuser_transform_channels\fP\fB);\fP \fI\fB @@ -780,6 +762,14 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.5rc3 \fI\fB +\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP + +\fI\fB + +\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP + +\fI\fB + .SH DESCRIPTION The .I libpng @@ -791,10 +781,10 @@ 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.2.5rc3 - September 18, 2002 + libpng version 1.2.7 - September 12, 2004 Updated and distributed by Glenn Randers-Pehrson - - Copyright (c) 1998-2002 Glenn Randers-Pehrson + + Copyright (c) 1998-2004 Glenn Randers-Pehrson For conditions of distribution and use, see copyright notice in png.h. @@ -828,19 +818,23 @@ Libpng was written as a companion to the PNG specification, as a way of reducing the amount of time and effort it takes to support the PNG file format in application programs. -The PNG-1.2 specification is available at -and at . +The PNG specification (second edition), November 2003, is available as +a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at + The PNG-1.0 specification is available -as RFC 2083 and as a +as RFC 2083 and as a W3C Recommendation . Some additional chunks are described in the special-purpose public chunks -documents at . +documents at . Other information about PNG, and the latest version of libpng, can be found at the PNG home -page, -and at . +page, . Most users will not have to modify the library significantly; advanced users may want to modify it more. All attempts were made to make it as @@ -873,7 +867,6 @@ same instance of a structure. Note: thread safety may be defeated by use of some of the MMX assembler code in pnggccrd.c, which is only compiled when the user defines PNG_THREAD_UNSAFE_OK. - .SH II. Structures There are two main structures that are important to libpng, png_struct @@ -1091,6 +1084,28 @@ To inform libpng about your function, use png_set_read_status_fn(png_ptr, read_row_callback); +.SS Width and height limits + +The PNG specification allows the width and height of an image to be as +large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns. +Since very few applications really need to process such large images, +we have imposed an arbitrary 1-million limit on rows and columns. +Larger images will be rejected immediately with a png_error() call. If +you wish to override this limit, you can use + + png_set_user_limits(png_ptr, width_max, height_max); + +to set your own limits, or use width_max = height_max = 0x7fffffffL +to allow all valid dimensions (libpng may reject some very large images +anyway because of potential buffer overflow conditions). + +You should put this statement after you create the PNG structure and +before calling png_read_info(), png_read_png(), or png_process_data(). +If you need to retrieve the limits that are being applied, use + + width_max = png_get_user_width_max(png_ptr); + height_max = png_get_user_height_max(png_ptr); + .SS Unknown-chunk handling Now you get to set the way the library processes unknown chunks in the @@ -1099,23 +1114,31 @@ behavior is that known chunks will be parsed into information in various info_ptr members; unknown chunks will be discarded. To change this, you can call: - png_set_keep_unknown_chunks(png_ptr, info_ptr, keep, + png_set_keep_unknown_chunks(png_ptr, keep, chunk_list, num_chunks); - keep - 0: do not keep - 1: keep only if safe-to-copy - 2: keep even if unsafe-to-copy + keep - 0: do not handle as unknown + 1: do not keep + 2: keep only if safe-to-copy + 3: keep even if unsafe-to-copy + You can use these definitions: + PNG_HANDLE_CHUNK_AS_DEFAULT 0 + PNG_HANDLE_CHUNK_NEVER 1 + PNG_HANDLE_CHUNK_IF_SAFE 2 + PNG_HANDLE_CHUNK_ALWAYS 3 chunk_list - list of chunks affected (a byte string, five bytes per chunk, NULL or '\0' if num_chunks is 0) num_chunks - number of chunks affected; if 0, all - unknown chunks are affected + unknown chunks are affected. If nonzero, + only the chunks in the list are affected Unknown chunks declared in this way will be saved as raw data onto a list of png_unknown_chunk structures. If a chunk that is normally known to libpng is named in the list, it will be handled as unknown, according to the "keep" directive. If a chunk is named in successive instances of png_set_keep_unknown_chunks(), the final instance will -take precedence. +take precedence. The IHDR and IEND chunks should not be named in +chunk_list; if they are, libpng will process them normally anyway. .SS The high-level read interface @@ -1158,6 +1181,9 @@ then png_read_image(), and finally png_read_end(). (The final parameter of this call is not yet used. Someday it might point to transformation parameters required by some future input transform.) +You must use png_transforms and not call any png_set_transform() functions +when you use png_read_png(). + After you have called png_read_png(), you can retrieve the image data with @@ -1170,8 +1196,14 @@ where row_pointers is an array of pointers to the pixel data for each row: If you know your image size and pixel size ahead of time, you can allocate row_pointers prior to calling png_read_png() with + if (height > PNG_UINT_32_MAX/png_sizeof(png_byte)) + png_error (png_ptr, + "Image is too tall to process in memory"); + if (width > PNG_UINT_32_MAX/pixel_size) + png_error (png_ptr, + "Image is too wide to process in memory"); row_pointers = png_malloc(png_ptr, - height*sizeof(png_bytep)); + height*png_sizeof(png_bytep)); for (int i=0; i + The contributing authors would like to thank all those who helped with testing, bug fixes, and patience. This wouldn't have been @@ -3842,13 +3893,14 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.2.5rc3 - September 18, 2002: +Libpng version 1.2.7 - September 12, 2004: Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. -Currently maintained by Glenn Randers-Pehrson (randeg@alum.rpi.edu). +Currently maintained by Glenn Randers-Pehrson (glennrp@users.sourceforge.net). Supported by the PNG development group .br -(png-implement@ccrc.wustl.edu). +png-implement@ccrc.wustl.edu (subscription required; write to +majordomo@ccrc.wustl.edu with "subscribe png-implement" in the message). .SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE: @@ -3859,7 +3911,14 @@ included in the libpng distribution, the latter shall prevail.) If you modify libpng you may insert additional notices immediately following this sentence. -libpng versions 1.0.7, July 1, 2000, through 1.2.5rc3, September 18, 2002, are +libpng version 1.2.6, September 12, 2004, is +Copyright (c) 2004 Glenn Randers-Pehrson, and is +distributed according to the same disclaimer and license as libpng-1.2.5 +with the following individual added to the list of Contributing Authors + + Cosmin Truta + +libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are distributed according to the same disclaimer and license as libpng-1.0.6 with the following individuals added to the list of Contributing Authors @@ -3950,8 +4009,8 @@ Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a certification mark of the Open Source Initiative. Glenn Randers-Pehrson -randeg@alum.rpi.edu -September 18, 2002 +glennrp@users.sourceforge.net +September 12, 2004 .\" end of man page