X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4946a942d77cf51e00aa56404756e124d7c11411..b9060f332453f80bc4c3c6aa6d25f322452d4f5e:/src/png/libpng.txt diff --git a/src/png/libpng.txt b/src/png/libpng.txt index 66c89dc51d..4dec2dd3ae 100644 --- a/src/png/libpng.txt +++ b/src/png/libpng.txt @@ -1,9 +1,9 @@ libpng.txt - A description on how to use and modify libpng - libpng version 1.2.4 - July 8, 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. @@ -37,19 +37,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 @@ -82,7 +86,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. - II. Structures There are two main structures that are important to libpng, png_struct @@ -300,6 +303,28 @@ To inform libpng about your function, use png_set_read_status_fn(png_ptr, read_row_callback); +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); + Unknown-chunk handling Now you get to set the way the library processes unknown chunks in the @@ -308,23 +333,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. The high-level read interface @@ -367,6 +400,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 @@ -379,8 +415,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