X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2b5f62a0b2db198609b45dec622a018dae37008e..f572d6495f86d2ed65c270ce95952588ba76f20f:/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
- <randeg@alum.rpi.edu>
- Copyright (c) 1998-2002 Glenn Randers-Pehrson
+ <glennrp@users.sourceforge.net>
+ 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 <http://www.libpng.org/pub/png>
-and at <ftp://ftp.uu.net/graphics/png/documents/>.
+The PNG specification (second edition), November 2003, is available as
+a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
+<http://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://www.libpng.org/pub/png/documents/>
The PNG-1.0 specification is available
-as RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as a
+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
-documents at <ftp://ftp.uu.net/graphics/png/documents/>.
+documents at <http://www.libpng.org/pub/png/documents/>.
Other information
about PNG, and the latest version of libpng, can be found at the PNG home
-page, <http://www.libpng.org/pub/png/>
-and at <ftp://ftp.uu.net/graphics/png/>.
+page, <http://www.libpng.org/pub/png/>.
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<height, i++)
row_pointers[i]=png_malloc(png_ptr,
width*pixel_size);
@@ -1516,14 +1548,14 @@ unless the library has been told to transform it into another format.
For example, 4 bit/pixel paletted or grayscale data will be returned
2 pixels/byte with the leftmost pixel in the high-order bits of the
byte, unless png_set_packing() is called. 8-bit RGB data will be stored
-in RGB RGB RGB format unless png_set_filler() is called to insert filler
-bytes, either before or after each RGB triplet. 16-bit RGB data will
-be returned RRGGBB RRGGBB, with the most significant byte of the color
-value first, unless png_set_strip_16() is called to transform it to
-regular RGB RGB triplets, or png_set_filler() is called to insert
-filler bytes, either before or after each RRGGBB triplet. Similarly,
-8-bit or 16-bit grayscale data can be modified with png_set_filler()
-or png_set_strip_16().
+in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
+is called to insert filler bytes, either before or after each RGB triplet.
+16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
+byte of the color value first, unless png_set_strip_16() is called to
+transform it to regular RGB RGB triplets, or png_set_filler|add alpha()
+is called to insert filler bytes, either before or after each RRGGBB
+triplet. Similarly, 8-bit or 16-bit grayscale data can be modified with
+png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
The following code transforms grayscale images of less than 8 to 8 bits,
changes paletted images to RGB, and adds a full alpha channel if there is
@@ -1608,6 +1640,16 @@ does not affect images that already have full alpha channels. To add an
opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
will generate RGBA pixels.
+Note that png_set_filler() does not change the color type. If you want
+to do that, you can add a true alpha channel with
+
+ if (color_type == PNG_COLOR_TYPE_RGB ||
+ color_type == PNG_COLOR_TYPE_GRAY)
+ png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
+
+where "filler" contains the alpha value to assign to each pixel.
+This function became available in libpng-1.2.7.
+
If you are reading an image with an alpha channel, and you need the
data as ARGB instead of the normal PNG format RGBA:
@@ -2752,6 +2794,9 @@ then png_write_image(), and finally png_write_end().
(The final parameter of this call is not yet used. Someday it might point
to transformation parameters required by some future output transform.)
+You must use png_transforms and not call any png_set_transform() functions
+when you use png_write_png().
+
.SS The low-level write interface
If you are going the low-level route instead, you are now ready to
@@ -3101,7 +3146,6 @@ functions must be modified in the library at compile time. If you prefer
to use a different method of allocating and freeing data, you can use
png_create_read_struct_2() or png_create_write_struct_2() to register
your own functions as described above.
-
These functions also provide a void pointer that can be retrieved via
mem_ptr=png_get_mem_ptr(png_ptr);
@@ -3112,9 +3156,9 @@ Your replacement memory functions must have prototypes as follows:
png_size_t size);
void free_fn(png_structp png_ptr, png_voidp ptr);
-Your malloc_fn() should return NULL in case of failure. The png_malloc()
-function will call png_error() if it receives a NULL from the system
-memory allocator or from your replacement malloc_fn().
+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().
Input/Output in libpng is done through png_read() and png_write(),
which currently just call fread() and fwrite(). The FILE * is stored in
@@ -3564,7 +3608,6 @@ For more extensive examples of runtime querying, enabling and disabling
of optimized features, see contrib/gregbook/readpng2.c in the libpng
source-code distribution.
-
.SH VII. MNG support
The MNG specification (available at http://www.libpng.org/pub/mng) allows
@@ -3578,7 +3621,7 @@ png_permit_mng_features() function:
PNG_FLAG_MNG_EMPTY_PLTE
PNG_FLAG_MNG_FILTER_64
PNG_ALL_MNG_FEATURES
- feature_set is a png_32_uint that is the logical AND of
+ feature_set is a png_uint_32 that is the logical AND of
your mask with the set of MNG features that is
supported by the version of libpng that you are using.
@@ -3641,13 +3684,13 @@ application:
.SH IX. Y2K Compliance in libpng
-September 18, 2002
+September 12, 2004
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.5rc3 are Y2K compliant. It is my belief that earlier
+upward through 1.2.7 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
@@ -3782,9 +3825,19 @@ the first widely used release:
1.2.4rc1 13 10204 12.so.0.1.2.4rc1
1.0.14 10 10014 10.so.0.1.0.14
1.2.4 13 10204 12.so.0.1.2.4
- 1.2.5beta1,2 13 10205 12.so.0.1.2.5beta1,2
- 1.2.5rc1,3 13 10205 12.so.0.1.2.5rc1,3
- 1.0.15rc1,3 10 10015 10.so.0.1.0.15rc1,3
+ 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
+ 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
+ 1.0.15 10 10015 10.so.0.1.0.15
+ 1.2.5 13 10205 12.so.0.1.2.5
+ 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
+ 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
+ 1.0.16 10 10016 10.so.0.1.0.16
+ 1.2.6 13 10206 12.so.0.1.2.6
+ 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
+ 1.0.17rc1 10 10017 12.so.0.1.0.17rc1
+ 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
+ 1.0.17 10 10017 12.so.0.1.0.17
+ 1.2.7 13 10207 12.so.0.1.2.7
Henceforth the source version will match the shared-library minor
and patch numbers; the shared-library major version number will be
@@ -3801,7 +3854,7 @@ libpngpf(3), png(5)
.LP
.IR libpng :
.IP
-ftp://ftp.uu.net/graphics/png
+http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
http://www.libpng.org/pub/png
.LP
@@ -3811,8 +3864,6 @@ http://www.libpng.org/pub/png
.I libpng
or at
.br
-ftp://ftp.uu.net/pub/archiving/zip/zlib
-.br
ftp://ftp.info-zip.org/pub/infozip/zlib
.LP
@@ -3834,7 +3885,7 @@ and this library, the specification takes precedence.
.SH AUTHORS
This man page: Glenn Randers-Pehrson
-<randeg@alum.rpi.edu>
+<glennrp@users.sourceforge.net>
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