-.TH LIBPNG 3 "August 15, 2004"
+.TH LIBPNG 3 "September 12, 2004"
.SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6
+libpng \- Portable Network Graphics (PNG) Reference Library 1.2.7
.SH SYNOPSIS
\fI\fB
\fI\fB
+\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
+
\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP
\fI\fB
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
- libpng version 1.2.6 - August 15, 2004
+ libpng version 1.2.7 - September 12, 2004
Updated and distributed by Glenn Randers-Pehrson
<glennrp@users.sourceforge.net>
Copyright (c) 1998-2004 Glenn Randers-Pehrson
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
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
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 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
(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
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
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:
(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
having level = 0 will be printed. There aren't any such statements in
this version of libpng, but if you insert some they will be printed.
-%-%.SH VI. Runtime optimization
-%-%
-%-%A new feature in libpng 1.2.0 is the ability to dynamically switch between
-%-%standard and optimized versions of some routines. Currently these are
-%-%limited to three computationally intensive tasks when reading PNG files:
-%-%decoding row filters, expanding interlacing, and combining interlaced or
-%-%transparent row data with previous row data. Currently the optimized
-%-%versions are available only for x86 (Intel, AMD, etc.) platforms with
-%-%MMX support, though this may change in future versions. (For example,
-%-%the non-MMX assembler optimizations for zlib might become similarly
-%-%runtime-selectable in future releases, in which case libpng could be
-%-%extended to support them. Alternatively, the compile-time choice of
-%-%floating-point versus integer routines for gamma correction might become
-%-%runtime-selectable.)
-%-%
-%-%Because such optimizations tend to be very platform- and compiler-dependent,
-%-%both in how they are written and in how they perform, the new runtime code
-%-%in libpng has been written to allow programs to query, enable, and disable
-%-%either specific optimizations or all such optimizations. For example, to
-%-%enable all possible optimizations (bearing in mind that some "optimizations"
-%-%may actually run more slowly in rare cases):
-%-%
-%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
-%-% png_uint_32 mask, flags;
-%-%
-%-% flags = png_get_asm_flags(png_ptr);
-%-% mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
-%-% png_set_asm_flags(png_ptr, flags | mask);
-%-% #endif
-%-%
-%-%To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
-%-%by itself when calling png_get_asm_flagmask(); similarly for optimizing
-%-%only writing. To disable all optimizations:
-%-%
-%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
-%-% flags = png_get_asm_flags(png_ptr);
-%-% mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
-%-% png_set_asm_flags(png_ptr, flags & ~mask);
-%-% #endif
-%-%
-%-%To enable or disable only MMX-related features, use png_get_mmx_flagmask()
-%-%in place of png_get_asm_flagmask(). The mmx version takes one additional
-%-%parameter:
-%-%
-%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
-%-% int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
-%-% int compilerID;
-%-%
-%-% mask = png_get_mmx_flagmask(selection, &compilerID);
-%-% #endif
-%-%
-%-%On return, compilerID will indicate which version of the MMX assembler
-%-%optimizations was compiled. Currently two flavors exist: Microsoft
-%-%Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
-%-%On non-x86 platforms or on systems compiled without MMX optimizations, a
-%-%value of -1 is used.
-%-%
-%-%Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
-%-%all valid, settable optimization bits for the version of the library that's
-%-%currently in use. In the case of shared (dynamically linked) libraries,
-%-%this may include optimizations that did not exist at the time the code was
-%-%written and compiled. It is also possible, of course, to enable only known,
-%-%specific optimizations; for example:
-%-%
-%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
-%-% flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
-%-% | PNG_ASM_FLAG_MMX_READ_INTERLACE \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_UP \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
-%-% png_set_asm_flags(png_ptr, flags);
-%-% #endif
-%-%
-%-%This method would enable only the MMX read-optimizations available at the
-%-%time of libpng 1.2.0's release, regardless of whether a later version of
-%-%the DLL were actually being used. (Also note that these functions did not
-%-%exist in versions older than 1.2.0, so any attempt to run a dynamically
-%-%linked app on such an older version would fail.)
-%-%
-%-%To determine whether the processor supports MMX instructions at all, use
-%-%the png_mmx_support() function:
-%-%
-%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
-%-% mmxsupport = png_mmx_support();
-%-% #endif
-%-%
-%-%It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
-%-%is compiled but MMX is not supported by the processor, or 1 if MMX support
-%-%is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
-%-%and png_get_asm_flagmask() all may be called without allocating and ini-
-%-%tializing any PNG structures (for example, as part of a usage screen or
-%-%"about" box).
-%-%
-%-%The following code can be used to prevent an application from using the
-%-%thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
-%-%defined:
-%-%
-%-%#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
-%-% && defined(PNG_THREAD_UNSAFE_OK)
-%-% /* Disable thread-unsafe features of pnggccrd */
-%-% if (png_access_version() >= 10200)
-%-% {
-%-% png_uint_32 mmx_disable_mask = 0;
-%-% png_uint_32 asm_flags;
-%-%
-%-% mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
-%-% | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
-%-% asm_flags = png_get_asm_flags(png_ptr);
-%-% png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
-%-% }
-%-%#endif
-%-%
-%-%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 VI. MNG support
+.SH VI. Runtime optimization
+
+A new feature in libpng 1.2.0 is the ability to dynamically switch between
+standard and optimized versions of some routines. Currently these are
+limited to three computationally intensive tasks when reading PNG files:
+decoding row filters, expanding interlacing, and combining interlaced or
+transparent row data with previous row data. Currently the optimized
+versions are available only for x86 (Intel, AMD, etc.) platforms with
+MMX support, though this may change in future versions. (For example,
+the non-MMX assembler optimizations for zlib might become similarly
+runtime-selectable in future releases, in which case libpng could be
+extended to support them. Alternatively, the compile-time choice of
+floating-point versus integer routines for gamma correction might become
+runtime-selectable.)
+
+Because such optimizations tend to be very platform- and compiler-dependent,
+both in how they are written and in how they perform, the new runtime code
+in libpng has been written to allow programs to query, enable, and disable
+either specific optimizations or all such optimizations. For example, to
+enable all possible optimizations (bearing in mind that some "optimizations"
+may actually run more slowly in rare cases):
+
+ #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
+ png_uint_32 mask, flags;
+
+ flags = png_get_asm_flags(png_ptr);
+ mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
+ png_set_asm_flags(png_ptr, flags | mask);
+ #endif
+
+To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
+by itself when calling png_get_asm_flagmask(); similarly for optimizing
+only writing. To disable all optimizations:
+
+ #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
+ flags = png_get_asm_flags(png_ptr);
+ mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
+ png_set_asm_flags(png_ptr, flags & ~mask);
+ #endif
+
+To enable or disable only MMX-related features, use png_get_mmx_flagmask()
+in place of png_get_asm_flagmask(). The mmx version takes one additional
+parameter:
+
+ #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
+ int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
+ int compilerID;
+
+ mask = png_get_mmx_flagmask(selection, &compilerID);
+ #endif
+
+On return, compilerID will indicate which version of the MMX assembler
+optimizations was compiled. Currently two flavors exist: Microsoft
+Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
+On non-x86 platforms or on systems compiled without MMX optimizations, a
+value of -1 is used.
+
+Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
+all valid, settable optimization bits for the version of the library that's
+currently in use. In the case of shared (dynamically linked) libraries,
+this may include optimizations that did not exist at the time the code was
+written and compiled. It is also possible, of course, to enable only known,
+specific optimizations; for example:
+
+ #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
+ flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
+ | PNG_ASM_FLAG_MMX_READ_INTERLACE \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_UP \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
+ png_set_asm_flags(png_ptr, flags);
+ #endif
+
+This method would enable only the MMX read-optimizations available at the
+time of libpng 1.2.0's release, regardless of whether a later version of
+the DLL were actually being used. (Also note that these functions did not
+exist in versions older than 1.2.0, so any attempt to run a dynamically
+linked app on such an older version would fail.)
+
+To determine whether the processor supports MMX instructions at all, use
+the png_mmx_support() function:
+
+ #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
+ mmxsupport = png_mmx_support();
+ #endif
+
+It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
+is compiled but MMX is not supported by the processor, or 1 if MMX support
+is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
+and png_get_asm_flagmask() all may be called without allocating and ini-
+tializing any PNG structures (for example, as part of a usage screen or
+"about" box).
+
+The following code can be used to prevent an application from using the
+thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
+defined:
+
+#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \
+ && defined(PNG_THREAD_UNSAFE_OK)
+ /* Disable thread-unsafe features of pnggccrd */
+ if (png_access_version() >= 10200)
+ {
+ png_uint_32 mmx_disable_mask = 0;
+ png_uint_32 asm_flags;
+
+ mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
+ | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
+ asm_flags = png_get_asm_flags(png_ptr);
+ png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
+ }
+#endif
+
+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
certain extensions to PNG for PNG images that are embedded in MNG datastreams.
them. You may wish to consider using libmng (available at
http://www.libmng.com) instead.
-.SH VII. Changes to Libpng from version 0.88
+.SH VIII. Changes to Libpng from version 0.88
It should be noted that versions of libpng later than 0.96 are not
distributed by the original libpng author, Guy Schalnat, nor by
png_uint_32 application_vn = PNG_LIBPNG_VER;
-.SH VII. Y2K Compliance in libpng
+.SH IX. Y2K Compliance in libpng
-August 15, 2004
+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.6 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
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
.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
.I libpng
or at
.br
-ftp://ftp.uu.net/pub/archiving/zip/zlib
-.br
ftp://ftp.info-zip.org/pub/infozip/zlib
.LP
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.2.6 - August 15, 2004:
+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 (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:
If you modify libpng you may insert additional notices immediately following
this sentence.
-libpng version 1.2.6, August 15, 2004, is
+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
Glenn Randers-Pehrson
glennrp@users.sourceforge.net
-August 15, 2004
+September 12, 2004
.\" end of man page
projects / wxWidgets.git / blobdiff