-.TH LIBPNG 3 "August 15, 2004"
+.TH LIBPNG 3 "September 23, 2010"
.SH NAME
-libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6
+libpng \- Portable Network Graphics (PNG) Reference Library 1.4.4
.SH SYNOPSIS
\fI\fB
\fI\fB
-\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\fP\fB);\fP
+\fBvoid png_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
+
+\fI\fB
+
+\fBvoid png_chunk_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
\fI\fB
\fI\fB
-\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP
-
-\fI\fB
-
-\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP
-
-\fI\fB
-
-\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\fP\fB);\fP
-
-\fI\fB
-
\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
\fI\fB
\fI\fB
+\fBpng_uint_32 png_get_chunk_cache_max (png_structp \fIpng_ptr\fP\fB);\fP
+
+\fI\fB
+
\fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
+\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
+
+\fI\fB
+
\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fI\fB
+\fBpng_int_32 png_get_int_32 (png_bytep \fIbuf\fP\fB);\fP
+
+\fI\fB
+
\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fI\fB
+\fBpng_alloc_size_t png_get_chunk_malloc_max (png_structp \fIpng_ptr\fP\fB);\fP
+
+\fI\fB
+
\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fI\fB
-\fBpng_uint_32 png_get_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_values\fP\fB);\fP
+\fBpng_uint_32 png_get_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_color\fP\fB);\fP
+
+\fI\fB
+
+\fB/* This function is really an inline macro. \fI*/
+
+\fBpng_uint_16 png_get_uint_16 (png_bytep \fIbuf\fP\fB);\fP
+
+\fI\fB
+
+\fBpng_uint_32 png_get_uint_31 (png_bytep \fIbuf\fP\fB);\fP
+
+\fI\fB
+
+\fB/* This function is really an inline macro. \fI*/
+
+\fBpng_uint_32 png_get_uint_32 (png_bytep \fIbuf\fP\fB);\fP
\fI\fB
\fI\fB
-\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
-
-\fI\fB
-
\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP
\fI\fB
\fI\fB
-\fBDEPRECATED: void png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP
-
-\fI\fB
-
-\fBDEPRECATED: void png_info_init_2 (png_infopp \fP\fIptr_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP
-
-\fI\fB
-
-\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
+\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
+\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
\fI\fB
\fI\fB
-\fBpng_voidp png_memcpy_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
-
-\fI\fB
-
\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP
\fI\fB
-\fBpng_voidp png_memset_check (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_uint_32 \fIsize\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
+\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP
\fI\fB
-\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP
+\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP
\fI\fB
-\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP
+\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBvoid png_read_destroy (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_infop \fIend_info_ptr\fP\fB);\fP
+\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
\fI\fB
-\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
+\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
\fI\fB
-\fBDEPRECATED: void png_read_init (png_structp \fIpng_ptr\fP\fB);\fP
+\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
\fI\fB
-\fBDEPRECATED: void png_read_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\fP\fB);\fP
+\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
\fI\fB
-\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
-\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
+\fBpng_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP
\fI\fB
-\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
+\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP
\fI\fB
-\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
+\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP
\fI\fB
-\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
+\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
\fI\fB
+\fBvoid png_set_chunk_cache_max (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIuser_chunk_cache_max\fP\fB);\fP
+
+\fI\fB
+
\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
\fI\fB
\fI\fB
-\fBvoid png_set_dither (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_dither\fP\fB);\fP
+\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP
\fI\fB
-\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP
+\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
-\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
+\fBvoid png_set_expand_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP
\fI\fB
\fI\fB
+\fBjmp_buf* png_set_longjmp_fn (png_structp \fP\fIpng_ptr\fP\fB, png_longjmp_ptr \fP\fIlongjmp_fn\fP\fB, size_t \fIjmp_buf_size\fP\fB);\fP
+
+\fI\fB
+
+\fBvoid png_set_chunk_malloc_max (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIuser_chunk_cache_max\fP\fB);\fP
+
+\fI\fB
+
\fBvoid png_set_mem_fn(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
\fI\fB
\fI\fB
+\fBvoid png_set_quantize (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_quantize\fP\fB);\fP
+
+\fI\fB
+
\fBvoid png_set_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fIread_data_fn\fP\fB);\fP
\fI\fB
\fI\fB
-\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_values\fP\fB);\fP
+\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_color\fP\fB);\fP
\fI\fB
\fI\fB
-\fBvoid png_write_destroy (png_structp \fIpng_ptr\fP\fB);\fP
-
-\fI\fB
-
\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fI\fB
-\fBDEPRECATED: void png_write_init (png_structp \fIpng_ptr\fP\fB);\fP
-
-\fI\fB
-
-\fBDEPRECATED: void png_write_init_2 (png_structpp \fP\fIptr_ptr\fP\fB, png_const_charp \fP\fIuser_png_ver\fP\fB, png_size_t \fP\fIpng_struct_size\fP\fB, png_size_t \fIpng_info_size\fP\fB);\fP
-
-\fI\fB
-
\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
\fI\fB
\fI\fB
+\fBvoid png_write_sig (png_structp \fIpng_ptr\fP\fB);\fP
+
+\fI\fB
+
\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\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.4.4 - September 23, 2010
Updated and distributed by 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.
+ <glennrp at users.sourceforge.net>
+ Copyright (c) 1998-2010 Glenn Randers-Pehrson
- based on:
+ This document is released under the libpng license.
+ For conditions of distribution and use, see the disclaimer
+ and license in png.h
+
+ Based on:
+
+ libpng versions 0.97, January 1998, through 1.4.4 - September 23, 2010
+ Updated and distributed by Glenn Randers-Pehrson
+ Copyright (c) 1998-2010 Glenn Randers-Pehrson
libpng 1.0 beta 6 version 0.96 May 28, 1997
Updated and distributed by Andreas Dilger
will need. We assume that libpng is already installed; see the
INSTALL file for instructions on how to install libpng.
+For examples of libpng usage, see the files "example.c", "pngtest.c",
+and the files in the "contrib" directory, all of which are included in
+the libpng distribution.
+
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/>. 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 <ftp://ftp.uu.net/graphics/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/>.
+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 <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
instances of the structures. Each thread should have its own
png_struct and png_info instances, and thus its own image.
Libpng does not protect itself against two threads using the
-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.
-
+same instance of a structure.
.SH II. Structures
will also want to insure that you are, in fact, dealing with a PNG
file. Libpng provides a simple check to see if a file is a PNG file.
To use it, pass in the first 1 to 8 bytes of the file to the function
-png_sig_cmp(), and it will return 0 if the bytes match the corresponding
-bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes
-you pass in, the greater the accuracy of the prediction.
+png_sig_cmp(), and it will return 0 (false) if the bytes match the
+corresponding bytes of the PNG signature, or nonzero (true) otherwise.
+Of course, the more bytes you pass in, the greater the accuracy of the
+prediction.
If you are intending to keep the file pointer open for use in libpng,
you must ensure you don't read more than 8 bytes from the beginning
}
If you would rather avoid the complexity of setjmp/longjmp issues,
-you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
+you can compile libpng with PNG_NO_SETJMP, in which case
errors will result in a call to PNG_ABORT() which defaults to abort().
+You can #define PNG_ABORT() to a function that does something
+more useful than abort(), as long as your function does not
+return.
+
Now you need to set up the input code. The default for libpng is to
use the C function fread(). If you use this, you will need to pass a
valid FILE * in the function png_init_io(). Be sure that the file is
png_set_sig_bytes(png_ptr, number);
+You can change the zlib compression buffer size to be used while
+reading compressed data with
+
+ png_set_compression_buffer_size(png_ptr, buffer_size);
+
+where the default size is 8192 bytes. Note that the buffer size
+is changed immediately and the buffer is reallocated immediately,
+instead of setting a flag to be acted upon later.
+
.SS Setting up callback code
You can set up a callback function to handle any unknown chunks in the
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 */
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.
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
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
-this, you can call:
+various info_ptr members while unknown chunks will be discarded. This
+behavior can be wasteful if your application will never use some known
+chunk types. 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:
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 User 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);
+
+The PNG specification sets no limit on the number of ancillary chunks
+allowed in a PNG datastream. You can impose a limit on the total number
+of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
+
+ png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
+
+where 0x7fffffffL means unlimited. You can retrieve this limit with
+
+ chunk_cache_max = png_get_chunk_cache_max(png_ptr);
+
+This limit also applies to the number of buffers that can be allocated
+by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
+
+You can also set a limit on the amount of memory that a compressed chunk
+other than IDAT can occupy, with
+
+ png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
+
+and you can retrieve the limit with
+
+ chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
+
+Any chunks that would cause either of these limits to be exceeded will
+be ignored.
+
.SS The high-level read interface
At this point there are two ways to proceed; through the high-level
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
+ PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
+ to RGB (or GA to RGBA)
(This excludes setting a background color, doing gamma transformation,
-dithering, and setting filler.) If this is the case, simply do this:
+quantizing, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL)
-where png_transforms is an integer containing the logical OR of
-some set of transformation flags. This call is equivalent to png_read_info(),
+where png_transforms is an integer containing the bitwise OR of some
+set of transformation flags. This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask,
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
"Image is too wide to process in memory");
row_pointers = png_malloc(png_ptr,
height*png_sizeof(png_bytep));
+ for (int i=0; i<height, i++)
+ row_pointers[i]=NULL; /* security precaution */
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
width*pixel_size);
for PNG 1.0)
interlace_type - (PNG_INTERLACE_NONE or
PNG_INTERLACE_ADAM7)
- Any or all of interlace_type, compression_type, of
+
+ Any or all of interlace_type, compression_type, or
filter_method can be NULL if you are
not interested in their values.
+ Note that png_get_IHDR() returns 32-bit data into
+ the application's width and height variables.
+ This is an unsafe situation if these are 16-bit
+ variables. In such situations, the
+ png_get_image_width() and png_get_image_height()
+ functions described below are safer.
+
+ width = png_get_image_width(png_ptr,
+ info_ptr);
+ height = png_get_image_height(png_ptr,
+ info_ptr);
+ bit_depth = png_get_bit_depth(png_ptr,
+ info_ptr);
+ color_type = png_get_color_type(png_ptr,
+ info_ptr);
+ filter_method = png_get_filter_type(png_ptr,
+ info_ptr);
+ compression_type = png_get_compression_type(png_ptr,
+ info_ptr);
+ interlace_type = png_get_interlace_type(png_ptr,
+ info_ptr);
+
channels = png_get_channels(png_ptr, info_ptr);
channels - number of channels of info for the
color type (valid values are 1 (GRAY,
be in signature[4] through signature[7]
(see png_set_sig_bytes())).
-
- width = png_get_image_width(png_ptr,
- info_ptr);
- height = png_get_image_height(png_ptr,
- info_ptr);
- bit_depth = png_get_bit_depth(png_ptr,
- info_ptr);
- color_type = png_get_color_type(png_ptr,
- info_ptr);
- filter_method = png_get_filter_type(png_ptr,
- info_ptr);
- compression_type = png_get_compression_type(png_ptr,
- info_ptr);
- interlace_type = png_get_interlace_type(png_ptr,
- info_ptr);
-
-
These are also important, but their validity depends on whether the chunk
has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
data has been read, or zero if it is missing. The parameters to the
-png_get_<chunk> are set directly if they are simple data types, or a pointer
-into the info_ptr is returned for any complex types.
+png_get_<chunk> are set directly if they are simple data types, or a
+pointer into the info_ptr is returned for any complex types.
png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette);
whichever are appropriate for the
given color type (png_color_16)
- png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
- &trans_values);
- trans - array of transparent entries for
- palette (PNG_INFO_tRNS)
- trans_values - graylevel or color sample values of
+ png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
+ &num_trans, &trans_color);
+ trans_alpha - array of alpha (transparency)
+ entries for palette (PNG_INFO_tRNS)
+ trans_color - graylevel or color sample values of
the single transparent color for
non-paletted images (PNG_INFO_tRNS)
num_trans - number of transparent entries
string for unknown).
text_ptr[i].lang_key - keyword in UTF-8
(empty string for unknown).
+ Note that the itxt_length, lang, and lang_key
+ members of the text_ptr structure only exist
+ when the library is built with iTXt chunk support.
+
num_text - number of comments (same as
num_comments; you can put NULL here
to avoid the duplication)
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() or
+png_set_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
png_set_palette_to_rgb(png_ptr);
if (color_type == PNG_COLOR_TYPE_GRAY &&
- bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr);
+ bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
if (png_get_valid(png_ptr, info_ptr,
PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
readability. In some future version they may actually do different
things.
+As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
+added. It expands the sample depth without changing tRNS to alpha.
+
+As of libpng version 1.4.4, not all possible expansions are supported.
+
+In the following table, the 01 means grayscale with depth<8, 31 means
+indexed with depth<8, other numerals represent the color type, "T" means
+the tRNS chunk is present, A means an alpha channel is present, and O
+means tRNS or alpha is present but all pixels in the image are opaque.
+
+ FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
+ TO
+ 01 -
+ 31 -
+ 0 1 -
+ 0T -
+ 0O -
+ 2 GX -
+ 2T -
+ 2O -
+ 3 1 -
+ 3T -
+ 3O -
+ 4A T -
+ 4O -
+ 6A GX TX TX -
+ 6O GX TX -
+
+Within the matrix,
+ "-" means the transformation is not supported.
+ "X" means the transformation is obtained by png_set_expand().
+ "1" means the transformation is obtained by
+ png_set_expand_gray_1_2_4_to_8
+ "G" means the transformation is obtained by
+ png_set_gray_to_rgb().
+ "P" means the transformation is obtained by
+ png_set_expand_palette_to_rgb().
+ "T" means the transformation is obtained by
+ png_set_tRNS_to_alpha().
+
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.
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next
-higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
-8 bits/sample in the range [0, 255]). However, it is also possible to
-convert the PNG pixel data back to the original bit depth of the image.
-This call reduces the pixels back down to the original bit depth:
+higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
+to 8 bits/sample in the range [0, 255]). However, it is also possible
+to convert the PNG pixel data back to the original bit depth of the
+image. This call reduces the pixels back down to the original bit depth:
png_color_8p sig_bit;
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 was added 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 default values approximate those recommended in the Charles
Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
-Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net
+Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>
Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
png_set_gamma(png_ptr, screen_gamma, 0.45455);
If you need to reduce an RGB file to a paletted file, or if a paletted
-file has more entries then will fit on your screen, png_set_dither()
+file has more entries then will fit on your screen, png_set_quantize()
will do that. Note that this is a simple match dither that merely
finds the closest color available. This should work fairly well with
optimized palettes, and fairly badly with linear color cubes. If you
png_get_hIST(png_ptr, info_ptr,
&histogram);
- png_set_dither(png_ptr, palette, num_palette,
+ png_set_quantize(png_ptr, palette, num_palette,
max_screen_colors, histogram, 1);
}
else
png_color std_color_cube[MAX_SCREEN_COLORS] =
{ ... colors ... };
- png_set_dither(png_ptr, std_color_cube,
+ png_set_quantize(png_ptr, std_color_cube,
MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
NULL,0);
}
.SS Finishing a sequential read
-After you are finished reading the image through either the high- or
-low-level interfaces, you can finish reading the file. If you are
+After you are finished reading the image through the
+low-level interface, you can finish reading the file. If you are
interested in comments or time, which may be stored either before or
after the image data, you should pass the separate png_info struct if
you want to keep the comments from before and after the image
png_free_data(png_ptr, info_ptr, mask, seq)
mask - identifies data to be freed, a mask
- containing the logical OR of one or
+ containing the bitwise OR of one or
more of
PNG_FREE_PLTE, PNG_FREE_TRNS,
PNG_FREE_HIST, PNG_FREE_ICCP,
This function may be safely called when the relevant storage has
already been freed, or has not yet been allocated, or was allocated
-by the user and not by libpng, and will in those
-cases do nothing. The "seq" parameter is ignored if only one item
-of the selected data type, such as PLTE, is allowed. If "seq" is not
--1, and multiple items are allowed for the data type identified in
-the mask, such as text or sPLT, only the n'th item in the structure
-is freed, where n is "seq".
+by the user and not by libpng, and will in those cases do nothing.
+The "seq" parameter is ignored if only one item of the selected data
+type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
+are allowed for the data type identified in the mask, such as text or
+sPLT, only the n'th item in the structure is freed, where n is "seq".
The default behavior is only to free data that was allocated internally
by libpng. This can be changed, so that libpng will not free the data,
application, your application must not separately free those members.
The png_free_data() function will turn off the "valid" flag for anything
-it frees. If you need to turn the flag off for a chunk that was freed by your
-application instead of by libpng, you can use
+it frees. If you need to turn the flag off for a chunk that was freed by
+your application instead of by libpng, you can use
png_set_invalid(png_ptr, info_ptr, mask);
mask - identifies the chunks to be made invalid,
- containing the logical OR of one or
+ containing the bitwise OR of one or
more of
PNG_INFO_gAMA, PNG_INFO_sBIT,
PNG_INFO_cHRM, PNG_INFO_PLTE,
return;
If you would rather avoid the complexity of setjmp/longjmp issues,
-you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
+you can compile libpng with PNG_NO_SETJMP, in which case
errors will result in a call to PNG_ABORT() which defaults to abort().
+You can #define PNG_ABORT() to a function that does something
+more useful than abort(), as long as your function does not
+return.
+
Now you need to set up the output code. The default for libpng is to
use the C function fwrite(). If you use this, you will need to pass a
valid FILE * in the function png_init_io(). Be sure that the file is
png_init_io(png_ptr, fp);
+If you are embedding your PNG into a datastream such as MNG, and don't
+want libpng to write the 8-byte signature, or if you have already
+written the signature in your application, use
+
+ png_set_sig_bytes(png_ptr, 8);
+
+to inform libpng that it should not write a signature.
+
.SS Write callbacks
At this point, you can set up a callback function that will be
July 1999 PNG specification, version 1.2) or 64 (if you are writing
a PNG datastream that is to be embedded in a MNG datastream). The third
parameter is a flag that indicates which filter type(s) are to be tested
-for each scanline. See the PNG specification for details on the specific filter
-types.
+for each scanline. See the PNG specification for details on the specific
+filter types.
/* turn on or off filtering, and/or choose
specific filters. You can use either a single
- PNG_FILTER_VALUE_NAME or the logical OR of one
+ PNG_FILTER_VALUE_NAME or the bitwise OR of one
or more PNG_FILTER_NAME masks. */
png_set_filter(png_ptr, 0,
PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
- PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE |
+ PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
PNG_ALL_FILTERS);
can also be
PNG_INTRAPIXEL_DIFFERENCING)
+If you call png_set_IHDR(), the call must appear before any of the
+other png_set_*() functions, because they might require access to some of
+the IHDR settings. The remaining png_set_*() functions can be called
+in any order.
+
+If you wish, you can reset the compression_type, interlace_type, or
+filter_method later by calling png_set_IHDR() again; if you do this, the
+width, height, bit_depth, and color_type must be the same in each call.
+
png_set_PLTE(png_ptr, info_ptr, palette,
num_palette);
palette - the palette for the file
appropriate for the given color type
(png_color_16)
- png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
- trans_values);
- trans - array of transparent entries for
- palette (PNG_INFO_tRNS)
- trans_values - graylevel or color sample values of
- the single transparent color for
+ png_set_tRNS(png_ptr, info_ptr, trans_alpha,
+ num_trans, trans_color);
+ trans_alpha - array of alpha (transparency)
+ entries for palette (PNG_INFO_tRNS)
+ trans_color - graylevel or color sample values
+ (in order red, green, blue) of the
+ single transparent color for
non-paletted images (PNG_INFO_tRNS)
num_trans - number of transparent entries
(PNG_INFO_tRNS)
empty for unknown).
text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
or empty for unknown).
+ Note that the itxt_length, lang, and lang_key
+ members of the text_ptr structure only exist
+ when the library is built with iTXt chunk support.
+
num_text - number of comments
png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
- PNG_TRANSFORM_STRIP_FILLER Strip out filler bytes.
+ PNG_TRANSFORM_STRIP_FILLER Strip out filler
+ bytes (deprecated).
+ PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
+ filler bytes
+ PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
+ filler bytes
If you have valid image data in the info structure (you can use
png_set_rows() to put image data in the info structure), simply do this:
png_write_png(png_ptr, info_ptr, png_transforms, NULL)
-where png_transforms is an integer containing the logical OR of some set of
+where png_transforms is an integer containing the bitwise OR of some set of
transformation flags. This call is equivalent to png_write_info(),
followed the set of transformations indicated by the transform mask,
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
Note that there is one transformation you may need to do before
png_write_info(). In PNG files, the alpha channel in an image is the
-level of opacity. If your data is supplied as a level of
-transparency, you can invert the alpha channel before you write it, so
-that 0 is fully transparent and 255 (in 8-bit or paletted images) or
-65535 (in 16-bit images) is fully opaque, with
+level of opacity. If your data is supplied as a level of transparency,
+you can invert the alpha channel before you write it, so that 0 is
+fully transparent and 255 (in 8-bit or paletted images) or 65535
+(in 16-bit images) is fully opaque, with
png_set_invert_alpha(png_ptr);
png_write_row(png_ptr, row_pointer);
-When the file is interlaced, things can get a good deal more
-complicated. The only currently (as of the PNG Specification
-version 1.2, dated July 1999) defined interlacing scheme for PNG files
-is the "Adam7" interlace scheme, that breaks down an
-image into seven smaller images of varying size. libpng will build
-these images for you, or you can do them yourself. If you want to
-build them yourself, see the PNG specification for details of which
-pixels to write when.
+When the file is interlaced, things can get a good deal more complicated.
+The only currently (as of the PNG Specification version 1.2, dated July
+1999) defined interlacing scheme for PNG files is the "Adam7" interlace
+scheme, that breaks down an image into seven smaller images of varying
+size. libpng will build these images for you, or you can do them
+yourself. If you want to build them yourself, see the PNG specification
+for details of which pixels to write when.
If you don't want libpng to handle the interlacing details, just
use png_set_interlace_handling() and call png_write_rows() the
number_of_passes =
png_set_interlace_handling(png_ptr);
-This will return the number of passes needed. Currently, this
-is seven, but may change if another interlace type is added.
+This will return the number of passes needed. Currently, this is seven,
+but may change if another interlace type is added.
Then write the complete image number_of_passes times.
png_write_rows(png_ptr, row_pointers,
number_of_rows);
-As some of these rows are not used, and thus return immediately,
-you may want to read about interlacing in the PNG specification,
-and only update the rows that are actually used.
+As some of these rows are not used, and thus return immediately, you may
+want to read about interlacing in the PNG specification, and only update
+the rows that are actually used.
.SS Finishing a sequential write
png_free_data(png_ptr, info_ptr, mask, seq)
mask - identifies data to be freed, a mask
- containing the logical OR of one or
+ containing the bitwise OR of one or
more of
PNG_FREE_PLTE, PNG_FREE_TRNS,
PNG_FREE_HIST, PNG_FREE_ICCP,
This function may be safely called when the relevant storage has
already been freed, or has not yet been allocated, or was allocated
-by the user and not by libpng, and will in those
-cases do nothing. The "seq" parameter is ignored if only one item
-of the selected data type, such as PLTE, is allowed. If "seq" is not
--1, and multiple items are allowed for the data type identified in
-the mask, such as text or sPLT, only the n'th item in the structure
-is freed, where n is "seq".
-
-If you allocated data such as a palette that you passed
-in to libpng with png_set_*, you must not free it until just before the call to
+by the user and not by libpng, and will in those cases do nothing.
+The "seq" parameter is ignored if only one item of the selected data
+type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
+are allowed for the data type identified in the mask, such as text or
+sPLT, only the n'th item in the structure is freed, where n is "seq".
+
+If you allocated data such as a palette that you passed in to libpng
+with png_set_*, you must not free it until just before the call to
png_destroy_write_struct().
The default behavior is only to free data that was allocated internally
.SH V. Modifying/Customizing libpng:
-There are three issues here. The first is changing how libpng does
+There are two issues here. The first is changing how libpng does
standard things like memory allocation, input/output, and error handling.
The second deals with more complicated things like adding new chunks,
adding new transformations, and generally changing how libpng works.
Both of those are compile-time issues; that is, they are generally
determined at the time the code is written, and there is rarely a need
-to provide the user with a means of changing them. The third is a
-run-time issue: choosing between and/or tuning one or more alternate
-versions of computationally intensive routines; specifically, optimized
-assembly-language (and therefore compiler- and platform-dependent)
-versions.
+to provide the user with a means of changing them.
Memory allocation, input/output, and error handling
in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
these functions, call the appropriate png_set_*_fn() function.
-Memory allocation is done through the functions png_malloc()
-and png_free(). These currently just call the standard C functions. If
-your pointers can't access more then 64K at a time, you will want to set
-MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling
-memory allocation on a platform will change between applications, these
-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
+Memory allocation is done through the functions png_malloc(), png_calloc(),
+and png_free(). These currently just call the standard C functions.
+png_calloc() calls png_malloc() and then png_memset() to clear the newly
+allocated memory to zero. If your pointers can't access more then 64K
+at a time, you will want to set MAXSEG_64K in zlib.h. Since it is
+unlikely that the method of handling memory allocation on a platform
+will change between applications, these 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);
Your replacement memory functions must have prototypes as follows:
png_voidp malloc_fn(png_structp png_ptr,
- png_size_t size);
+ png_alloc_size_t size);
void free_fn(png_structp png_ptr, png_voidp ptr);
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
png_bytep data, png_size_t length);
void user_flush_data(png_structp png_ptr);
+The user_read_data() function is responsible for detecting and
+handling end-of-data errors.
+
Supplying NULL for the read, write, or flush functions sets them back
-to using the default C stream functions. It is an error to read from
-a write stream, and vice versa.
+to using the default C stream functions, which expect the io_ptr to
+point to a standard *FILE structure. It is probably a mistake
+to use NULL for one of write_data_fn and output_flush_fn but not both
+of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
+It is an error to read from a write stream, and vice versa.
Error handling in libpng is done through png_error() and png_warning().
Errors handled through png_error() are fatal, meaning that png_error()
should never return to its caller. Currently, this is handled via
setjmp() and longjmp() (unless you have compiled libpng with
-PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
-but you could change this to do things like exit() if you should wish.
+PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
+but you could change this to do things like exit() if you should wish,
+as long as your function does not return.
On non-fatal errors, png_warning() is called
to print a warning message, and then control returns to the calling code.
catch exception handling methods. This makes the code much easier to write,
as there is no need to check every return code of every function call.
However, there are some uncertainties about the status of local variables
-after a longjmp, so the user may want to be careful about doing anything after
-setjmp returns non-zero besides returning itself. Consult your compiler
-documentation for more details. For an alternative approach, you may wish
-to use the "cexcept" facility (see http://cexcept.sourceforge.net).
+after a longjmp, so the user may want to be careful about doing anything
+after setjmp returns non-zero besides returning itself. Consult your
+compiler documentation for more details. For an alternative approach, you
+may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
.SS Custom chunks
If you need to read or write custom chunks, you may need to get deeper
into the libpng code. The library now has mechanisms for storing
and writing chunks of unknown type; you can even declare callbacks
-for custom chunks. Hoewver, this may not be good enough if the
+for custom chunks. However, this may not be good enough if the
library code itself needs to know about interactions between your
chunk and existing `intrinsic' chunks.
If you need to write a new intrinsic chunk, first read the PNG
-specification. Acquire a first level of
-understanding of how it works. Pay particular attention to the
-sections that describe chunk names, and look at how other chunks were
-designed, so you can do things similarly. Second, check out the
-sections of libpng that read and write chunks. Try to find a chunk
-that is similar to yours and use it as a template. More details can
-be found in the comments inside the code. It is best to handle unknown
-chunks in a generic method, via callback functions, instead of by
-modifying libpng functions.
+specification. Acquire a first level of understanding of how it works.
+Pay particular attention to the sections that describe chunk names,
+and look at how other chunks were designed, so you can do things
+similarly. Second, check out the sections of libpng that read and
+write chunks. Try to find a chunk that is similar to yours and use
+it as a template. More details can be found in the comments inside
+the code. It is best to handle unknown chunks in a generic method,
+via callback functions, instead of by modifying libpng functions.
If you wish to write your own transformation for the data, look through
the part of the code that does the transformations, and check out some of
.SS Configuring for compiler xxx:
-All includes for libpng are in pngconf.h. If you need to add/change/delete
-an include, this is the place to do it. The includes that are not
-needed outside libpng are protected by the PNG_INTERNAL definition,
-which is only defined for those routines inside libpng itself. The
-files in libpng proper only include png.h, which includes pngconf.h.
+All includes for libpng are in pngconf.h. If you need to add, change
+or delete an include, this is the place to do it.
+The includes that are not needed outside libpng are placed in pngpriv.h,
+which is only used by the routines inside libpng itself.
+The files in libpng proper only include pngpriv.h and png.h, which
+in turn includes pngconf.h.
.SS Configuring zlib:
is called for the first time.)
filters = PNG_FILTER_NONE | PNG_FILTER_SUB
- PNG_FILTER_UP | PNG_FILTER_AVE |
+ PNG_FILTER_UP | PNG_FILTER_AVG |
PNG_FILTER_PAETH | PNG_ALL_FILTERS;
png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
or all four,
along with directives to turn on any of the capabilities that you do
-want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
-the extra transformations but still leave the library fully capable of reading
-and writing PNG files with all known public chunks
-Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
-produces a library that is incapable of reading or writing ancillary chunks.
-If you are not using the progressive reading capability, you can
-turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
-this with the INTERLACING capability, which you'll still have).
+want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
+transformations but still leave the library fully capable of reading
+and writing PNG files with all known public chunks. Use of the
+PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
+that is incapable of reading or writing ancillary chunks. If you are
+not using the progressive reading capability, you can turn that off
+with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
+capability, which you'll still have).
All the reading and writing specific code are in separate files, so the
linker should only grab the files it needs. However, if you want 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
The MNG specification (available at http://www.libpng.org/pub/mng) allows
png_permit_mng_features() function:
feature_set = png_permit_mng_features(png_ptr, mask)
- mask is a png_uint_32 containing the logical OR of the
+ mask is a png_uint_32 containing the bitwise OR of the
features you want to enable. These include
PNG_FLAG_MNG_EMPTY_PLTE
PNG_FLAG_MNG_FILTER_64
PNG_ALL_MNG_FEATURES
- feature_set is a png_uint_32 that is the logical AND of
+ feature_set is a png_uint_32 that is the bitwise AND of
your mask with the set of MNG features that is
supported by the version of libpng that you are using.
png_uint_32 application_vn = PNG_LIBPNG_VER;
-.SH VII. Y2K Compliance in libpng
+.SH VIII. Changes to Libpng from version 1.0.x to 1.2.x
+
+Support for user memory management was enabled by default. To
+accomplish this, the functions png_create_read_struct_2(),
+png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
+png_malloc_default(), and png_free_default() were added.
+
+Support for the iTXt chunk has been enabled by default as of
+version 1.2.41.
+
+Support for certain MNG features was enabled.
+
+Support for numbered error messages was added. However, we never got
+around to actually numbering the error messages. The function
+png_set_strip_error_numbers() was added (Note: the prototype for this
+function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
+builds of libpng-1.2.15. It was restored in libpng-1.2.36).
+
+The png_malloc_warn() function was added at libpng-1.2.3. This issues
+a png_warning and returns NULL instead of aborting when it fails to
+acquire the requested memory allocation.
+
+Support for setting user limits on image width and height was enabled
+by default. The functions png_set_user_limits(), png_get_user_width_max(),
+and png_get_user_height_max() were added at libpng-1.2.6.
+
+The png_set_add_alpha() function was added at libpng-1.2.7.
+
+The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
+Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
+tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
+deprecated.
+
+A number of macro definitions in support of runtime selection of
+assembler code features (especially Intel MMX code support) were
+added at libpng-1.2.0:
+
+ PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
+ PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
+ 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_ASM_FLAGS_INITIALIZED
+ PNG_MMX_READ_FLAGS
+ PNG_MMX_FLAGS
+ PNG_MMX_WRITE_FLAGS
+ PNG_MMX_FLAGS
+
+We added the following functions in support of runtime
+selection of assembler code features:
+
+ png_get_mmx_flagmask()
+ png_set_mmx_thresholds()
+ png_get_asm_flags()
+ png_get_mmx_bitdepth_threshold()
+ png_get_mmx_rowbytes_threshold()
+ png_set_asm_flags()
+
+We replaced all of these functions with simple stubs in libpng-1.2.20,
+when the Intel assembler code was removed due to a licensing issue.
+
+These macros are deprecated:
+
+ PNG_READ_TRANSFORMS_NOT_SUPPORTED
+ PNG_PROGRESSIVE_READ_NOT_SUPPORTED
+ PNG_NO_SEQUENTIAL_READ_SUPPORTED
+ PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
+ PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
+ PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
+
+They have been replaced, respectively, by:
+
+ PNG_NO_READ_TRANSFORMS
+ PNG_NO_PROGRESSIVE_READ
+ PNG_NO_SEQUENTIAL_READ
+ PNG_NO_WRITE_TRANSFORMS
+ PNG_NO_READ_ANCILLARY_CHUNKS
+ PNG_NO_WRITE_ANCILLARY_CHUNKS
+
+PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
+deprecated since libpng-1.0.16 and libpng-1.2.6.
+
+The function
+ png_check_sig(sig, num)
+was replaced with
+ !png_sig_cmp(sig, 0, num)
+It has been deprecated since libpng-0.90.
+
+The function
+ png_set_gray_1_2_4_to_8()
+which also expands tRNS to alpha was replaced with
+ png_set_expand_gray_1_2_4_to_8()
+which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
+
+.SH IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
+
+Private libpng prototypes and macro definitions were moved from
+png.h and pngconf.h into a new pngpriv.h header file.
+
+Functions png_set_benign_errors(), png_benign_error(), and
+png_chunk_benign_error() were added.
+
+Support for setting the maximum amount of memory that the application
+will allocate for reading chunks was added, as a security measure.
+The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
+were added to the library.
+
+We implemented support for I/O states by adding png_ptr member io_state
+and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
+
+We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
+input transforms.
+
+Checking for and reporting of errors in the IHDR chunk is more thorough.
+
+Support for global arrays was removed, to improve thread safety.
+
+Some obsolete/deprecated macros and functions have been removed.
-August 15, 2004
+Typecasted NULL definitions such as
+ #define png_voidp_NULL (png_voidp)NULL
+were eliminated. If you used these in your application, just use
+NULL instead.
+
+The png_struct and info_struct members "trans" and "trans_values" were
+changed to "trans_alpha" and "trans_color", respectively.
+
+The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
+were removed.
+
+The PNG_1_0_X and PNG_1_2_X macros were eliminated.
+
+The PNG_LEGACY_SUPPORTED macro was eliminated.
+
+Many WIN32_WCE #ifdefs were removed.
+
+The functions png_read_init(info_ptr), png_write_init(info_ptr),
+png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
+have been removed. They have been deprecated since libpng-0.95.
+
+The png_permit_empty_plte() was removed. It has been deprecated
+since libpng-1.0.9. Use png_permit_mng_features() instead.
+
+We removed the obsolete stub functions png_get_mmx_flagmask(),
+png_set_mmx_thresholds(), png_get_asm_flags(),
+png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
+png_set_asm_flags(), and png_mmx_supported()
+
+We removed the obsolete png_check_sig(), png_memcpy_check(), and
+png_memset_check() functions. Instead use !png_sig_cmp(), png_memcpy(),
+and png_memset(), respectively.
+
+The function png_set_gray_1_2_4_to_8() was removed. It has been
+deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
+png_set_expand_gray_1_2_4_to_8() because the former function also
+expanded palette images.
+
+We changed the prototype for png_malloc() from
+ png_malloc(png_structp png_ptr, png_uint_32 size)
+to
+ png_malloc(png_structp png_ptr, png_alloc_size_t size)
+
+This also applies to the prototype for the user replacement malloc_fn().
+
+The png_calloc() function was added and is used in place of
+of "png_malloc(); png_memset();" except in the case in png_read_png()
+where the array consists of pointers; in this case a "for" loop is used
+after the png_malloc() to set the pointers to NULL, to give robust.
+behavior in case the application runs out of memory part-way through
+the process.
+
+We changed the prototypes of png_get_compression_buffer_size() and
+png_set_compression_buffer_size() to work with png_size_t instead of
+png_uint_32.
+
+Support for numbered error messages was removed by default, since we
+never got around to actually numbering the error messages. The function
+png_set_strip_error_numbers() was removed from the library by default.
+
+The png_zalloc() and png_zfree() functions are no longer exported.
+The png_zalloc() function no longer zeroes out the memory that it
+allocates.
+
+Support for dithering was disabled by default in libpng-1.4.0, because
+been well tested and doesn't actually "dither". The code was not
+removed, however, and could be enabled by building libpng with
+PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
+was reenabled, but the function was renamed png_set_quantize() to
+reflect more accurately what it actually does. At the same time,
+the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
+PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS.
+
+We removed the trailing '.' from the warning and error messages.
+
+.SH X. Detecting libpng
+
+The png_get_io_ptr() function has been present since libpng-0.88, has never
+changed, and is unaffected by conditional compilation macros. It is the
+best choice for use in configure scripts for detecting the presence of any
+libpng version since 0.88. In an autoconf "configure.in" you could use
+
+ AC_CHECK_LIB(png, png_get_io_ptr, ...
+
+.SH XI. Source code repository
+
+Since about February 2009, version 1.2.34, libpng has been under "git" source
+control. The git repository was built from old libpng-x.y.z.tar.gz files
+going back to version 0.70. You can access the git repository (read only)
+at
+
+ git://libpng.git.sourceforge.net/gitroot/libpng
+
+or you can browse it via "gitweb" at
+
+ http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
+
+Patches can be sent to glennrp at users.sourceforge.net or to
+png-mng-implement at lists.sourceforge.net or you can upload them to
+the libpng bug tracker at
+
+ http://libpng.sourceforge.net
+
+.SH XII. Coding style
+
+Our coding style is similar to the "Allman" style, with curly
+braces on separate lines:
+
+ if (condition)
+ {
+ action;
+ }
+
+ else if (another condition)
+ {
+ another action;
+ }
+
+The braces can be omitted from simple one-line actions:
+
+ if (condition)
+ return (0);
+
+We use 3-space indentation, except for continued statements which
+are usually indented the same as the first line of the statement
+plus four more spaces.
+
+For macro definitions we use 2-space indentation, always leaving the "#"
+in the first column.
+
+ #ifndef PNG_NO_FEATURE
+ # ifndef PNG_FEATURE_SUPPORTED
+ # define PNG_FEATURE_SUPPORTED
+ # endif
+ #endif
+
+Comments appear with the leading "/*" at the same indentation as
+the statement that follows the comment:
+
+ /* Single-line comment */
+ statement;
+
+ /* This is a multiple-line
+ * comment.
+ */
+ statement;
+
+Very short comments can be placed after the end of the statement
+to which they pertain:
+
+ statement; /* comment */
+
+We don't use C++ style ("//") comments. We have, however,
+used them in the past in some now-abandoned MMX assembler
+code.
+
+Functions and their curly braces are not indented, and
+exported functions are marked with PNGAPI:
+
+ /* This is a public function that is visible to
+ * application programers. It does thus-and-so.
+ */
+ void PNGAPI
+ png_exported_function(png_ptr, png_info, foo)
+ {
+ body;
+ }
+
+The prototypes for all exported functions appear in png.h,
+above the comment that says
+
+ /* Maintainer: Put new public prototypes here ... */
+
+We mark all non-exported functions with "/* PRIVATE */"":
+
+ void /* PRIVATE */
+ png_non_exported_function(png_ptr, png_info, foo)
+ {
+ body;
+ }
+
+The prototypes for non-exported functions (except for those in
+pngtest) appear in
+pngpriv.h
+above the comment that says
+
+ /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
+
+The names of all exported functions and variables begin
+with "png_", and all publicly visible C preprocessor
+macros begin with "PNG_".
+
+We put a space after each comma and after each semicolon
+in "for" statments, and we put spaces before and after each
+C binary operator and after "for" or "while", and before
+"?". We don't put a space between a typecast and the expression
+being cast, nor do we put one between a function name and the
+left parenthesis that follows it:
+
+ for (i = 2; i > 0; --i)
+ y[i] = a(x) + (int)b;
+
+We prefer #ifdef and #ifndef to #if defined() and if !defined()
+when there is only one macro being tested.
+
+We do not use the TAB character for indentation in the C sources.
+
+Lines do not exceed 80 characters.
+
+Other rules can be inferred by inspecting the libpng source.
+
+.SH XIII. Y2K Compliance in libpng
+
+September 23, 2010
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.4.4 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
+ 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
+ 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5
+ 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
+ 1.0.18 10 10018 12.so.0.1.0.18
+ 1.2.8 13 10208 12.so.0.1.2.8
+ 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
+ 1.2.9beta4-11 13 10209 12.so.0.9[.0]
+ 1.2.9rc1 13 10209 12.so.0.9[.0]
+ 1.2.9 13 10209 12.so.0.9[.0]
+ 1.2.10beta1-7 13 10210 12.so.0.10[.0]
+ 1.2.10rc1-2 13 10210 12.so.0.10[.0]
+ 1.2.10 13 10210 12.so.0.10[.0]
+ 1.4.0beta1-6 14 10400 14.so.0.0[.0]
+ 1.2.11beta1-4 13 10210 12.so.0.11[.0]
+ 1.4.0beta7-8 14 10400 14.so.0.0[.0]
+ 1.2.11 13 10211 12.so.0.11[.0]
+ 1.2.12 13 10212 12.so.0.12[.0]
+ 1.4.0beta9-14 14 10400 14.so.0.0[.0]
+ 1.2.13 13 10213 12.so.0.13[.0]
+ 1.4.0beta15-36 14 10400 14.so.0.0[.0]
+ 1.4.0beta37-87 14 10400 14.so.14.0[.0]
+ 1.4.0rc01 14 10400 14.so.14.0[.0]
+ 1.4.0beta88-109 14 10400 14.so.14.0[.0]
+ 1.4.0rc02-08 14 10400 14.so.14.0[.0]
+ 1.4.0 14 10400 14.so.14.0[.0]
+ 1.4.1beta01-03 14 10401 14.so.14.1[.0]
+ 1.4.1rc01 14 10401 14.so.14.1[.0]
+ 1.4.1beta04-12 14 10401 14.so.14.1[.0]
+ 1.4.1rc02-04 14 10401 14.so.14.1[.0]
+ 1.4.1 14 10401 14.so.14.1[.0]
+ 1.4.2beta01 14 10402 14.so.14.2[.0]
+ 1.4.2rc02-06 14 10402 14.so.14.2[.0]
+ 1.4.2 14 10402 14.so.14.2[.0]
+ 1.4.3beta01-05 14 10403 14.so.14.3[.0]
+ 1.4.3rc01-03 14 10403 14.so.14.3[.0]
+ 1.4.3 14 10403 14.so.14.3[.0]
+ 1.4.4beta01-08 14 10404 14.so.14.4[.0]
+ 1.4.4rc01-06 14 10404 14.so.14.4[.0]
Henceforth the source version will match the shared-library minor
and patch numbers; the shared-library major version number will be
release number plus "betaNN" or "rcN".
.SH "SEE ALSO"
-libpngpf(3), png(5)
+.BR "png"(5), " libpngpf"(3), " zlib"(3), " deflate"(5), " " and " zlib"(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
.I libpng
or at
.br
-ftp://ftp.uu.net/pub/archiving/zip/zlib
-.br
ftp://ftp.info-zip.org/pub/infozip/zlib
.LP
.SH AUTHORS
This man page: Glenn Randers-Pehrson
-<glennrp@users.sourceforge.net>
+<glennrp at 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
Thanks to Frank J. T. Wojcik for helping with the documentation.
-Libpng version 1.2.6 - August 15, 2004:
+Libpng version 1.4.4 - September 23, 2010:
Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
-Currently maintained by Glenn Randers-Pehrson (glennrp@users.sourceforge.net).
+Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
Supported by the PNG development group
.br
-(png-implement@ccrc.wustl.edu).
+png-mng-implement at lists.sf.net
+(subscription required; visit
+png-mng-implement at lists.sourceforge.net (subscription required; visit
+https://lists.sourceforge.net/lists/listinfo/png-mng-implement
+to subscribe).
.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
-Copyright (c) 2004 Glenn Randers-Pehrson, and is
+This code is released under the libpng license.
+
+libpng versions 1.2.6, August 15, 2004, through 1.4.4, September 23, 2010, are
+Copyright (c) 2004,2006-2007 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
certification mark of the Open Source Initiative.
Glenn Randers-Pehrson
-glennrp@users.sourceforge.net
-August 15, 2004
+glennrp at users.sourceforge.net
+September 23, 2010
.\" end of man page
projects / wxWidgets.git / blobdiff