diff options
Diffstat (limited to 'Build/source/libs/libpng/libpng.3')
-rw-r--r-- | Build/source/libs/libpng/libpng.3 | 109 |
1 files changed, 90 insertions, 19 deletions
diff --git a/Build/source/libs/libpng/libpng.3 b/Build/source/libs/libpng/libpng.3 index ae397476e1d..ef7fc5b2b31 100644 --- a/Build/source/libs/libpng/libpng.3 +++ b/Build/source/libs/libpng/libpng.3 @@ -1,6 +1,6 @@ -.TH LIBPNG 3 "February 18, 2008" +.TH LIBPNG 3 "May 8, 2008" .SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.2.25 +libpng \- Portable Network Graphics (PNG) Reference Library 1.2.29 .SH SYNOPSIS \fB #include <png.h>\fP @@ -410,14 +410,18 @@ 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.25 - February 18, 2008 + libpng version 1.2.29 - May 8, 2008 Updated and distributed by Glenn Randers-Pehrson <glennrp at users.sourceforge.net> Copyright (c) 1998-2008 Glenn Randers-Pehrson For conditions of distribution and use, see copyright notice in png.h. - based on: + Based on: + + libpng versions 0.97, January 1998, through 1.2.29 - May 8, 2008 + Updated and distributed by Glenn Randers-Pehrson + Copyright (c) 1998-2008 Glenn Randers-Pehrson libpng 1.0 beta 6 version 0.96 May 28, 1997 Updated and distributed by Andreas Dilger @@ -457,12 +461,14 @@ a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at The W3C and ISO documents have identical technical content. The PNG-1.2 specification is available at -<http://www.libpng.org/pub/png/documents/> +<http://www.libpng.org/pub/png/documents/>. 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://www.libpng.org/pub/png/documents/> and as a -W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some -additional chunks are described in the special-purpose public chunks +W3C Recommendation <http://www.w3.org/TR/REC.png.html>. + +Some additional chunks are described in the special-purpose public chunks documents at <http://www.libpng.org/pub/png/documents/>. Other information @@ -670,15 +676,19 @@ input stream. You must supply the function png_unknown_chunkp chunk); { /* The unknown chunk structure contains your - chunk data: */ + chunk data, along with similar data for any other + unknown chunks: */ + png_byte name[5]; png_byte *data; png_size_t size; + /* Note that libpng has already taken care of the CRC handling */ - /* put your code here. Return one of the - following: */ + /* put your code here. Search for your chunk in the + unknown chunk structure, process it, and return one + of the following: */ return (-n); /* chunk had an error */ return (0); /* did not recognize */ @@ -698,6 +708,11 @@ you can retrieve with png_get_user_chunk_ptr(png_ptr); +If you call the png_set_read_user_chunk_fn() function, then all unknown +chunks will be saved when read, in case your callback function will need +one or more of them. This behavior can be changed with the +png_set_keep_unknown_chunks() function, described below. + At this point, you can set up a callback function that will be called after each row has been read, which you can use to control a progress meter or the like. It's demonstrated in pngtest.c. @@ -742,13 +757,13 @@ If you need to retrieve the limits that are being applied, use Now you get to set the way the library processes unknown chunks in the input PNG stream. Both known and unknown chunks will be read. Normal behavior is that known chunks will be parsed into information in -various info_ptr members; unknown chunks will be discarded. To change +various info_ptr members while unknown chunks will be discarded. To change this, you can call: png_set_keep_unknown_chunks(png_ptr, keep, chunk_list, num_chunks); - keep - 0: do not handle as unknown - 1: do not keep + keep - 0: default unknown chunk handling + 1: ignore; do not keep 2: keep only if safe-to-copy 3: keep even if unsafe-to-copy You can use these definitions: @@ -771,6 +786,37 @@ instances of png_set_keep_unknown_chunks(), the final instance will take precedence. The IHDR and IEND chunks should not be named in chunk_list; if they are, libpng will process them normally anyway. +Here is an example of the usage of png_set_keep_unknown_chunks(), +where the private "vpAg" chunk will later be processed by a user chunk +callback function: + + png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'}; + + #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) + png_byte unused_chunks[]= + { + 104, 73, 83, 84, (png_byte) '\0', /* hIST */ + 105, 84, 88, 116, (png_byte) '\0', /* iTXt */ + 112, 67, 65, 76, (png_byte) '\0', /* pCAL */ + 115, 67, 65, 76, (png_byte) '\0', /* sCAL */ + 115, 80, 76, 84, (png_byte) '\0', /* sPLT */ + 116, 73, 77, 69, (png_byte) '\0', /* tIME */ + }; + #endif + + ... + + #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) + /* ignore all unknown chunks: */ + png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0); + /* except for vpAg: */ + png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); + /* also ignore unused known chunks: */ + png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks, + (int)sizeof(unused_chunks)/5); + #endif + + .SS The high-level read interface At this point there are two ways to proceed; through the high-level @@ -1214,6 +1260,7 @@ added. It expands the sample depth without changing tRNS to alpha. At the same time, png_set_gray_1_2_4_to_8() was deprecated, and it will be removed from a future version. + PNG can have files with 16 bits per channel. If you only can handle 8 bits per channel, this will strip the pixels down to 8 bit. @@ -2153,6 +2200,11 @@ Some of the more important parts of the png_info are: can also be PNG_INTRAPIXEL_DIFFERENCING) +If you call png_set_IHDR(), the call must appear before any of the +other png_set_*() functions, which might require access to some of +the IHDR settings. The remaining png_set_*() functions can be called +in any order. + png_set_PLTE(png_ptr, info_ptr, palette, num_palette); palette - the palette for the file @@ -2801,6 +2853,9 @@ Your malloc_fn() must return NULL in case of failure. The png_malloc() function will normally call png_error() if it receives a NULL from the system memory allocator or from your replacement malloc_fn(). +Your free_fn() will never be called with a NULL ptr, since libpng's +png_free() checks for NULL before calling free_fn(). + Input/Output in libpng is done through png_read() and png_write(), which currently just call fread() and fwrite(). The FILE * is stored in png_struct and is initialized via png_init_io(). If you wish to change @@ -3206,13 +3261,13 @@ application: .SH IX. Y2K Compliance in libpng -February 18, 2008 +May 8, 2008 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.2.25 are Y2K compliant. It is my belief that earlier +upward through 1.2.29 are Y2K compliant. It is my belief that earlier versions were also Y2K compliant. Libpng only has three year fields. One is a 2-byte unsigned integer that @@ -3428,6 +3483,22 @@ the first widely used release: 1.2.24 13 10224 12.so.0.24[.0] 1.2.25beta01-06 13 10225 12.so.0.25[.0] 1.2.25rc01-02 13 10225 12.so.0.25[.0] + 1.0.31 10 10031 10.so.0.31[.0] + 1.2.25 13 10225 12.so.0.25[.0] + 1.2.26beta01-06 13 10226 12.so.0.26[.0] + 1.2.26rc01 13 10226 12.so.0.26[.0] + 1.2.26 13 10226 12.so.0.26[.0] + 1.0.32 10 10032 10.so.0.32[.0] + 1.2.27beta01-06 13 10227 12.so.0.27[.0] + 1.2.27rc01 13 10227 12.so.0.27[.0] + 1.0.33 10 10033 10.so.0.33[.0] + 1.2.27 13 10227 12.so.0.27[.0] + 1.0.34 10 10034 10.so.0.34[.0] + 1.2.28 13 10228 12.so.0.28[.0] + 1.2.29beta01-03 13 10229 12.so.0.29[.0] + 1.2.29rc01 13 10229 12.so.0.29[.0] + 1.0.35 10 10035 10.so.0.35[.0] + 1.2.29 13 10229 12.so.0.29[.0] Henceforth the source version will match the shared-library minor and patch numbers; the shared-library major version number will be @@ -3463,7 +3534,7 @@ ftp://ftp.info-zip.org/pub/infozip/zlib .I libpng or at .br -ftp://ds.internic.net/rfc/rfc2083.txt +ftp://ftp.rfc-editor.org:/in-notes/rfc2083.txt .br or (as a W3C Recommendation) at .br @@ -3483,7 +3554,7 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.2.25 - February 18, 2008: +Libpng version 1.2.29 - May 8, 2008: Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net). @@ -3504,7 +3575,7 @@ 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.2.6, August 15, 2004, through 1.2.25, February 18, 2008, are +libpng versions 1.2.6, August 15, 2004, through 1.2.29, May 8, 2008, are Copyright (c) 2004,2006-2008 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 @@ -3603,7 +3674,7 @@ certification mark of the Open Source Initiative. Glenn Randers-Pehrson glennrp at users.sourceforge.net -February 18, 2008 +May 8, 2008 .\" end of man page |