summaryrefslogtreecommitdiff
path: root/Build/source/libs/libpng/libpng.3
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/libs/libpng/libpng.3')
-rw-r--r--Build/source/libs/libpng/libpng.3109
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