Google Git
Sign in
flutter / third_party / libpng / 1916f6ae420cd22eab26b1322072d09acb110ade / . / libpng.3
blob: bf573e055fe37ad3da2937842797bccfaa6a5d7f [file] [log] [blame]
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]1.TH LIBPNG 3 "August 14, 2008"
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]2.SH NAME
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]3libpng \- Portable Network Graphics (PNG) Reference Library 1.4.0beta30
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4.SH SYNOPSIS
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]5\fI\fB
6
7\fB#include <png.h>\fP
8
9\fI\fB
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]10
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]11\fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP
12
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]13\fI\fB
14
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]15\fBvoid png_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
16
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]17\fI\fB
18
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]19\fBvoid png_chunk_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
20
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]21\fI\fB
22
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]23\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]24
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]25\fI\fB
26
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]27\fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]28
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]29\fI\fB
30
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]31\fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]32
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]33\fI\fB
34
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]35\fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]36
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]37\fI\fB
38
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]39\fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]40
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]41\fI\fB
42
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]43\fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]44
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]45\fI\fB
46
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]47\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]48
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]49\fI\fB
50
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]51\fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]52
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]53\fI\fB
54
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]55\fBpng_structp png_create_read_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\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
56
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]57\fI\fB
58
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]59\fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]60
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]61\fI\fB
62
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]63\fBpng_structp png_create_write_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\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
64
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]65\fI\fB
66
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]67\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP
68
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]69\fI\fB
70
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]71\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP
72
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]73\fI\fB
74
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]75\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\fP\fB);\fP
76
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]77\fI\fB
78
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]79\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
80
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]81\fI\fB
82
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]83\fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP
84
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]85\fI\fB
86
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]87\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
88
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]89\fI\fB
90
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]91\fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
92
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]93\fI\fB
94
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]95\fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
96
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]97\fI\fB
98
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]99\fBvoid png_free_chunk_list (png_structp \fIpng_ptr\fP\fB);\fP
100
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]101\fI\fB
102
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]103\fBvoid png_free_default(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
104
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]105\fI\fB
106
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]107\fBvoid png_free_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]108
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]109\fI\fB
110
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]111\fBpng_byte png_get_bit_depth (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
112
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]113\fI\fB
114
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]115\fBpng_uint_32 png_get_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
116
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]117\fI\fB
118
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]119\fBpng_byte png_get_channels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
120
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]121\fI\fB
122
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]123\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
124
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]125\fI\fB
126
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]127\fBpng_uint_32 png_get_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
128
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]129\fI\fB
130
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]131\fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
132
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]133\fI\fB
134
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]135\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
136
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]137\fI\fB
138
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]139\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP
140
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]141\fI\fB
142
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]143\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP
144
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]145\fI\fB
146
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]147\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
148
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]149\fI\fB
150
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]151\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
152
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]153\fI\fB
154
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]155\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
156
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]157\fI\fB
158
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]159\fBpng_byte png_get_header_ver (png_structp \fIpng_ptr\fP\fB);\fP
160
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]161\fI\fB
162
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]163\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP
164
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]165\fI\fB
166
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]167\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
168
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]169\fI\fB
170
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]171\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]172
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]173\fI\fB
174
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]175\fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP
176
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]177\fI\fB
178
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]179\fBpng_uint_32 png_get_image_height (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
180
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]181\fI\fB
182
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]183\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
184
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]185\fI\fB
186
187\fB#if \fI!defined(PNG_1_0_X)
188
189\fBpng_int_32 png_get_int_32 (png_bytep \fIbuf\fP\fB);\fP
190
191\fI\fB#endif
192
193\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]194
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]195\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
196
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]197\fI\fB
198
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]199\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP
200
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]201\fI\fB
202
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]203\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP
204
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]205\fI\fB
206
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]207\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP
208
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]209\fI\fB
210
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]211\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP
212
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]213\fI\fB
214
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]215\fBpng_uint_32 png_get_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP
216
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]217\fI\fB
218
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]219\fBpng_uint_32 png_get_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
220
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]221\fI\fB
222
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]223\fBfloat png_get_pixel_aspect_ratio (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
224
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]225\fI\fB
226
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]227\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
228
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]229\fI\fB
230
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]231\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP
232
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]233\fI\fB
234
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]235\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP
236
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]237\fI\fB
238
239\fBpng_byte png_get_rgb_to_gray_status (png_structp \fIpng_ptr)
240
241\fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
242
243\fI\fB
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]244
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]245\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
246
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]247\fI\fB
248
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]249\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP
250
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]251\fI\fB
252
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]253\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
254
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]255\fI\fB
256
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]257\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]258
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]259\fI\fB
260
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]261\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP
262
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]263\fI\fB
264
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]265\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP
266
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]267\fI\fB
268
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]269\fBpng_uint_32 png_get_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP
270
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]271\fI\fB
272
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]273\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
274
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]275\fI\fB
276
Glenn Randers-Pehrsoneb580912008-07-30 14:47:09 -0500[diff] [blame]277\fB/* This function is really an inline macro. \fI*/
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]278
279\fBpng_uint_16 png_get_uint_16 (png_bytep \fIbuf\fP\fB);\fP
280
281\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]282
283\fBpng_uint_32 png_get_uint_31 (png_bytep \fIbuf\fP\fB);\fP
284
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]285\fI\fB
286
Glenn Randers-Pehrsoneb580912008-07-30 14:47:09 -0500[diff] [blame]287\fB/* This function is really an inline macro. \fI*/
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]288
Glenn Randers-Pehrsoneb580912008-07-30 14:47:09 -0500[diff] [blame]289\fBpng_uint_32 png_get_uint_32 (png_bytep \fIbuf\fP\fB);\fP
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]290
291\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]292
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]293\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP
294
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]295\fI\fB
296
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]297\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP
298
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]299\fI\fB
300
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]301\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP
302
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]303\fI\fB
304
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]305\fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP
306
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]307\fI\fB
308
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]309\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP
310
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]311\fI\fB
312
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]313\fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
314
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]315\fI\fB
316
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]317\fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]318
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]319\fI\fB
320
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]321\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]322
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]323\fI\fB
324
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]325\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
326
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]327\fI\fB
328
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]329\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]330
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]331\fI\fB
332
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]333\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]334
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]335\fI\fB
336
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]337\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
338
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]339\fI\fB
340
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]341\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
342
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]343\fI\fB
344
Glenn Randers-Pehrsonc1bfe682002-03-06 22:08:00 -0600[diff] [blame]345\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP
346
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]347\fI\fB
348
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]349\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]350
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]351\fI\fB
352
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]353\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]354
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]355\fI\fB
356
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]357\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]358
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]359\fI\fB
360
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]361\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP
362
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]363\fI\fB
364
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]365\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP
366
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]367\fI\fB
368
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]369\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
370
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]371\fI\fB
372
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]373\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
374
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]375\fI\fB
376
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]377\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
378
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]379\fI\fB
380
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]381\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
382
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]383\fI\fB
384
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]385\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
386
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]387\fI\fB
388
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]389\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
390
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]391\fI\fB
392
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]393\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
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]394
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]395\fI\fB
396
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]397\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
398
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]399\fI\fB
400
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]401\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
402
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]403\fI\fB
404
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]405\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
406
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]407\fI\fB
408
409\fB#if \fI!defined(PNG_1_0_X)
410
411\fBpng_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP
412
413\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]414
415\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP
416
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]417\fI\fB
418
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]419\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP
420
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]421\fI\fB
422
423\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
424
425\fI\fB#endif
426
427\fI\fB
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]428
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]429\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
430
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]431\fI\fB
432
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]433\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP
434
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]435\fI\fB
436
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]437\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP
438
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]439\fI\fB
440
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]441\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB, double \fP\fIblue_x\fP\fB, double \fIblue_y\fP\fB);\fP
442
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]443\fI\fB
444
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]445\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\fB, png_uint_32 \fP\fIgreen_y\fP\fB, png_uint_32 \fP\fIblue_x\fP\fB, png_uint_32 \fIblue_y\fP\fB);\fP
446
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]447\fI\fB
448
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]449\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
450
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]451\fI\fB
452
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]453\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
454
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]455\fI\fB
456
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]457\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP
458
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]459\fI\fB
460
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]461\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]462
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]463\fI\fB
464
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]465\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]466
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]467\fI\fB
468
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]469\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]470
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]471\fI\fB
472
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]473\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
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]474
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]475\fI\fB
476
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]477\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
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]478
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]479\fI\fB
480
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]481\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]482
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]483\fI\fB
484
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]485\fBvoid png_set_expand_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP
486
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]487\fI\fB
488
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]489\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]490
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]491\fI\fB
492
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]493\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]494
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]495\fI\fB
496
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]497\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]498
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]499\fI\fB
500
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]501\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]502
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]503\fI\fB
504
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]505\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]506
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]507\fI\fB
508
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]509\fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]510
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]511\fI\fB
512
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]513\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP
514
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]515\fI\fB
516
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]517\fBvoid png_set_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]518
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]519\fI\fB
520
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]521\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]522
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]523\fI\fB
524
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]525\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]526
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]527\fI\fB
528
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]529\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_charp \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]530
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]531\fI\fB
532
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]533\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]534
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]535\fI\fB
536
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]537\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP
538
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]539\fI\fB
540
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]541\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]542
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]543\fI\fB
544
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]545\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]546
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]547\fI\fB
548
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]549\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcompression_type\fP\fB, int \fIfilter_type\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]550
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]551\fI\fB
552
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]553\fBvoid png_set_keep_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIkeep\fP\fB, png_bytep \fP\fIchunk_list\fP\fB, int \fInum_chunks\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]554
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]555\fI\fB
556
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]557\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
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]558
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]559\fI\fB
560
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]561\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]562
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]563\fI\fB
564
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]565\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]566
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]567\fI\fB
568
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]569\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]570
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]571\fI\fB
572
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]573\fBvoid png_set_palette_to_rgb(png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]574
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]575\fI\fB
576
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]577\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, png_charpp \fIparams\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]578
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]579\fI\fB
580
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]581\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]582
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]583\fI\fB
584
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]585\fBvoid png_set_premultiply_alpha (png_structp \fIpng_ptr\fP\fB);\fP
586
587\fI\fB
588
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]589\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]590
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]591\fI\fB
592
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]593\fBvoid png_set_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fInum_palette\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]594
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]595\fI\fB
596
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]597\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
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]598
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]599\fI\fB
600
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]601\fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]602
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]603\fI\fB
604
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]605\fBvoid png_set_read_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIread_user_transform_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]606
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]607\fI\fB
608
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]609\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP
610
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]611\fI\fB
612
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]613\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_fixed_point \fP\fIred\fP\fB, png_fixed_point \fIgreen\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]614
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]615\fI\fB
616
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]617\fBvoid png_set_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytepp \fIrow_pointers\fP\fB);\fP
618
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]619\fI\fB
620
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]621\fBvoid png_set_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fIsig_bit\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]622
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]623\fI\fB
624
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]625\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP
626
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]627\fI\fB
628
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]629\fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]630
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]631\fI\fB
632
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]633\fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]634
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]635\fI\fB
636
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]637\fBvoid png_set_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fIsplt_ptr\fP\fB, int \fInum_spalettes\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]638
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]639\fI\fB
640
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]641\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]642
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]643\fI\fB
644
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]645\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]646
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]647\fI\fB
648
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]649\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]650
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]651\fI\fB
652
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]653\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]654
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]655\fI\fB
656
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]657\fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]658
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]659\fI\fB
660
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]661\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]662
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]663\fI\fB
664
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]665\fBvoid png_set_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fItext_ptr\fP\fB, int \fInum_text\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]666
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]667\fI\fB
668
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]669\fBvoid png_set_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fImod_time\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]670
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]671\fI\fB
672
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]673\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
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]674
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]675\fI\fB
676
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]677\fBvoid png_set_tRNS_to_alpha(png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]678
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]679\fI\fB
680
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]681\fBpng_uint_32 png_set_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkp \fP\fIunknowns\fP\fB, int \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP
682
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]683\fI\fB
684
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]685\fBvoid png_set_unknown_chunk_location(png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\fP\fB, int \fIlocation\fP\fB);\fP
686
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]687\fI\fB
688
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]689\fBvoid png_set_read_user_chunk_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_chunk_ptr\fP\fB, png_user_chunk_ptr \fIread_user_chunk_fn\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]690
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]691\fI\fB
692
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]693\fBvoid png_set_user_limits (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIuser_width_max\fP\fB, png_uint_32 \fIuser_height_max\fP\fB);\fP
694
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]695\fI\fB
696
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]697\fBvoid png_set_user_transform_info (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_transform_ptr\fP\fB, int \fP\fIuser_transform_depth\fP\fB, int \fIuser_transform_channels\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]698
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]699\fI\fB
700
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]701\fBvoid png_set_write_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fP\fIwrite_data_fn\fP\fB, png_flush_ptr \fIoutput_flush_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]702
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]703\fI\fB
704
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]705\fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]706
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]707\fI\fB
708
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]709\fBvoid png_set_write_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIwrite_user_transform_fn\fP\fB);\fP
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]710
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]711\fI\fB
712
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]713\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
714
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]715\fI\fB
716
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]717\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]718
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]719\fI\fB
720
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]721\fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]722
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]723\fI\fB
724
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]725\fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]726
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]727\fI\fB
728
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]729\fBvoid png_write_chunk (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]730
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]731\fI\fB
732
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]733\fBvoid png_write_chunk_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]734
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]735\fI\fB
736
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]737\fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]738
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]739\fI\fB
740
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]741\fBvoid png_write_chunk_start (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_uint_32 \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]742
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]743\fI\fB
744
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]745\fBvoid png_write_destroy (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]746
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]747\fI\fB
748
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]749\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]750
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]751\fI\fB
752
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]753\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]754
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]755\fI\fB
756
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]757\fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]758
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]759\fI\fB
760
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]761\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]762
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]763\fI\fB
764
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]765\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
766
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]767\fI\fB
768
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]769\fBvoid png_write_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
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]770
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]771\fI\fB
772
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]773\fBvoid png_write_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIrow\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]774
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]775\fI\fB
776
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]777\fBvoid png_write_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]778
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]779\fI\fB
780
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]781\fBvoid png_write_sig (png_structp \fIpng_ptr\fP\fB);\fP
782
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]783\fI\fB
784
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]785\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP
786
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]787\fI\fB
788
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]789\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP
790
Glenn Randers-Pehrson145f5c82008-07-10 09:13:13 -0500[diff] [blame]791\fI\fB
792
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]793.SH DESCRIPTION
794The
795.I libpng
796library supports encoding, decoding, and various manipulations of
797the Portable Network Graphics (PNG) format image files. It uses the
798.IR zlib(3)
799compression library.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]800Following is a copy of the libpng.txt file that accompanies libpng.
801.SH LIBPNG.TXT
802libpng.txt - A description on how to use and modify libpng
803
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]804 libpng version 1.4.0beta30 - August 14, 2008
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]805 Updated and distributed by Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]806 <glennrp at users.sourceforge.net>
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]807 Copyright (c) 1998-2005 Glenn Randers-Pehrson
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]808 For conditions of distribution and use, see copyright
809 notice in png.h.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]810
811 based on:
812
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]813 libpng 1.0 beta 6 version 0.96 May 28, 1997
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]814 Updated and distributed by Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]815 Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]816
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]817 libpng 1.0 beta 2 - version 0.88 January 26, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]818 For conditions of distribution and use, see copyright
819 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]820 Schalnat, Group 42, Inc.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]821
822 Updated/rewritten per request in the libpng FAQ
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]823 Copyright (c) 1995, 1996 Frank J. T. Wojcik
824 December 18, 1995 & January 20, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]825
826.SH I. Introduction
827
828This file describes how to use and modify the PNG reference library
829(known as libpng) for your own use. There are five sections to this
830file: introduction, structures, reading, writing, and modification and
831configuration notes for various special platforms. In addition to this
832file, example.c is a good starting point for using the library, as
833it is heavily commented and should include everything most people
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]834will need. We assume that libpng is already installed; see the
835INSTALL file for instructions on how to install libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]836
837Libpng was written as a companion to the PNG specification, as a way
838of reducing the amount of time and effort it takes to support the PNG
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]839file format in application programs.
840
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]841The PNG specification (second edition), November 2003, is available as
842a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
843<http://www.w3.org/TR/2003/REC-PNG-20031110/
844The W3C and ISO documents have identical technical content.
845
846The PNG-1.2 specification is available at
847<http://www.libpng.org/pub/png/documents/>
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]848
849The PNG-1.0 specification is available
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]850as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]851W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
852additional chunks are described in the special-purpose public chunks
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]853documents at <http://www.libpng.org/pub/png/documents/>.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]854
855Other information
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]856about PNG, and the latest version of libpng, can be found at the PNG home
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]857page, <http://www.libpng.org/pub/png/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]858
859Most users will not have to modify the library significantly; advanced
860users may want to modify it more. All attempts were made to make it as
861complete as possible, while keeping the code easy to understand.
862Currently, this library only supports C. Support for other languages
863is being considered.
864
865Libpng has been designed to handle multiple sessions at one time,
866to be easily modifiable, to be portable to the vast majority of
867machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
868to use. The ultimate goal of libpng is to promote the acceptance of
869the PNG file format in whatever way possible. While there is still
870work to be done (see the TODO file), libpng should cover the
871majority of the needs of its users.
872
873Libpng uses zlib for its compression and decompression of PNG files.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]874Further information about zlib, and the latest version of zlib, can
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]875be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]876The zlib compression utility is a general purpose utility that is
877useful for more than PNG files, and can be used without libpng.
878See the documentation delivered with zlib for more details.
879You can usually find the source files for the zlib utility wherever you
880find the libpng source files.
881
882Libpng is thread safe, provided the threads are using different
883instances of the structures. Each thread should have its own
884png_struct and png_info instances, and thus its own image.
885Libpng does not protect itself against two threads using the
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]886same instance of a structure. Note: thread safety may be defeated
887by use of some of the MMX assembler code in pnggccrd.c, which is only
888compiled when the user defines PNG_THREAD_UNSAFE_OK.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]889
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]890.SH II. Structures
891
892There are two main structures that are important to libpng, png_struct
893and png_info. The first, png_struct, is an internal structure that
894will not, for the most part, be used by a user except as the first
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]895variable passed to every libpng function call.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]896
897The png_info structure is designed to provide information about the
898PNG file. At one time, the fields of png_info were intended to be
899directly accessible to the user. However, this tended to cause problems
900with applications using dynamically loaded libraries, and as a result
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]901a set of interface functions for png_info (the png_get_*() and png_set_*()
902functions) was developed. The fields of png_info are still available for
903older applications, but it is suggested that applications use the new
904interfaces if at all possible.
905
906Applications that do make direct access to the members of png_struct (except
907for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
908and applications that make direct access to the members of png_info must
909be recompiled if they were compiled or loaded with libpng version 1.0.6,
910in which the members were in a different order. In version 1.0.7, the
911members of the png_info structure reverted to the old order, as they were
912in versions 0.97c through 1.0.5. Starting with version 2.0.0, both
913structures are going to be hidden, and the contents of the structures will
914only be accessible through the png_get/png_set functions.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]915
916The png.h header file is an invaluable reference for programming with libpng.
917And while I'm on the topic, make sure you include the libpng header file:
918
919#include <png.h>
920
921.SH III. Reading
922
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]923We'll now walk you through the possible functions to call when reading
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]924in a PNG file sequentially, briefly explaining the syntax and purpose
925of each one. See example.c and png.h for more detail. While
926progressive reading is covered in the next section, you will still
927need some of the functions discussed in this section to read a PNG
928file.
929
930.SS Setup
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]931
932You will want to do the I/O initialization(*) before you get into libpng,
933so if it doesn't work, you don't have much to undo. Of course, you
934will also want to insure that you are, in fact, dealing with a PNG
935file. Libpng provides a simple check to see if a file is a PNG file.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]936To use it, pass in the first 1 to 8 bytes of the file to the function
937png_sig_cmp(), and it will return 0 if the bytes match the corresponding
938bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes
939you pass in, the greater the accuracy of the prediction.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]940
941If you are intending to keep the file pointer open for use in libpng,
942you must ensure you don't read more than 8 bytes from the beginning
943of the file, and you also have to make a call to png_set_sig_bytes_read()
944with the number of bytes you read from the beginning. Libpng will
945then only check the bytes (if any) that your program didn't read.
946
947(*): If you are not using the standard I/O functions, you will need
948to replace them with custom functions. See the discussion under
949Customizing libpng.
950
951
952 FILE *fp = fopen(file_name, "rb");
953 if (!fp)
954 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]955 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]956 }
957 fread(header, 1, number, fp);
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]958 is_png = !png_sig_cmp(header, 0, number);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]959 if (!is_png)
960 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]961 return (NOT_PNG);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]962 }
963
964
965Next, png_struct and png_info need to be allocated and initialized. In
966order to ensure that the size of these structures is correct even with a
967dynamically linked libpng, there are functions to initialize and
968allocate the structures. We also pass the library version, optional
969pointers to error handling functions, and a pointer to a data struct for
970use by the error functions, if necessary (the pointer and functions can
971be NULL if the default error handlers are to be used). See the section
972on Changes to Libpng below regarding the old initialization functions.
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]973The structure allocation functions quietly return NULL if they fail to
974create the structure, so your application should check for that.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]975
976 png_structp png_ptr = png_create_read_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]977 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]978 user_error_fn, user_warning_fn);
979 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]980 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]981
982 png_infop info_ptr = png_create_info_struct(png_ptr);
983 if (!info_ptr)
984 {
985 png_destroy_read_struct(&png_ptr,
986 (png_infopp)NULL, (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]987 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]988 }
989
990 png_infop end_info = png_create_info_struct(png_ptr);
991 if (!end_info)
992 {
993 png_destroy_read_struct(&png_ptr, &info_ptr,
994 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]995 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]996 }
997
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]998If you want to use your own memory allocation routines,
999define PNG_USER_MEM_SUPPORTED and use
1000png_create_read_struct_2() instead of png_create_read_struct():
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1001
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1002 png_structp png_ptr = png_create_read_struct_2
1003 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1004 user_error_fn, user_warning_fn, (png_voidp)
1005 user_mem_ptr, user_malloc_fn, user_free_fn);
1006
1007The error handling routines passed to png_create_read_struct()
1008and the memory alloc/free routines passed to png_create_struct_2()
1009are only necessary if you are not using the libpng supplied error
1010handling and memory alloc/free functions.
1011
1012When libpng encounters an error, it expects to longjmp back
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1013to your routine. Therefore, you will need to call setjmp and pass
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1014your png_jmpbuf(png_ptr). If you read the file from different
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1015routines, you will need to update the jmpbuf field every time you enter
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1016a new routine that will call a png_*() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1017
1018See your documentation of setjmp/longjmp for your compiler for more
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1019information on setjmp/longjmp. See the discussion on libpng error
1020handling in the Customizing Libpng section below for more information
1021on the libpng error handling. If an error occurs, and libpng longjmp's
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1022back to your setjmp, you will want to call png_destroy_read_struct() to
1023free any memory.
1024
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1025 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1026 {
1027 png_destroy_read_struct(&png_ptr, &info_ptr,
1028 &end_info);
1029 fclose(fp);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1030 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1031 }
1032
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1033If you would rather avoid the complexity of setjmp/longjmp issues,
1034you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
1035errors will result in a call to PNG_ABORT() which defaults to abort().
1036
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1037Now you need to set up the input code. The default for libpng is to
1038use the C function fread(). If you use this, you will need to pass a
1039valid FILE * in the function png_init_io(). Be sure that the file is
1040opened in binary mode. If you wish to handle reading data in another
1041way, you need not call the png_init_io() function, but you must then
1042implement the libpng I/O methods discussed in the Customizing Libpng
1043section below.
1044
1045 png_init_io(png_ptr, fp);
1046
1047If you had previously opened the file and read any of the signature from
1048the beginning in order to see if this was a PNG file, you need to let
1049libpng know that there are some bytes missing from the start of the file.
1050
1051 png_set_sig_bytes(png_ptr, number);
1052
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1053.SS Setting up callback code
1054
1055You can set up a callback function to handle any unknown chunks in the
1056input stream. You must supply the function
1057
1058 read_chunk_callback(png_ptr ptr,
1059 png_unknown_chunkp chunk);
1060 {
1061 /* The unknown chunk structure contains your
1062 chunk data: */
1063 png_byte name[5];
1064 png_byte *data;
1065 png_size_t size;
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1066 /* Note that libpng has already taken care of
1067 the CRC handling */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1068
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1069 /* put your code here. Return one of the
1070 following: */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1071
1072 return (-n); /* chunk had an error */
1073 return (0); /* did not recognize */
1074 return (n); /* success */
1075 }
1076
1077(You can give your function another name that you like instead of
1078"read_chunk_callback")
1079
1080To inform libpng about your function, use
1081
1082 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1083 read_chunk_callback);
1084
1085This names not only the callback function, but also a user pointer that
1086you can retrieve with
1087
1088 png_get_user_chunk_ptr(png_ptr);
1089
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1090At this point, you can set up a callback function that will be
1091called after each row has been read, which you can use to control
1092a progress meter or the like. It's demonstrated in pngtest.c.
1093You must supply a function
1094
Glenn Randers-Pehrsone68f5a32001-05-14 09:20:53 -0500[diff] [blame]1095 void read_row_callback(png_ptr ptr, png_uint_32 row,
1096 int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1097 {
1098 /* put your code here */
1099 }
1100
1101(You can give it another name that you like instead of "read_row_callback")
1102
1103To inform libpng about your function, use
1104
1105 png_set_read_status_fn(png_ptr, read_row_callback);
1106
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]1107.SS Width and height limits
1108
1109The PNG specification allows the width and height of an image to be as
1110large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1111Since very few applications really need to process such large images,
1112we have imposed an arbitrary 1-million limit on rows and columns.
1113Larger images will be rejected immediately with a png_error() call. If
1114you wish to override this limit, you can use
1115
1116 png_set_user_limits(png_ptr, width_max, height_max);
1117
1118to set your own limits, or use width_max = height_max = 0x7fffffffL
1119to allow all valid dimensions (libpng may reject some very large images
1120anyway because of potential buffer overflow conditions).
1121
1122You should put this statement after you create the PNG structure and
1123before calling png_read_info(), png_read_png(), or png_process_data().
1124If you need to retrieve the limits that are being applied, use
1125
1126 width_max = png_get_user_width_max(png_ptr);
1127 height_max = png_get_user_height_max(png_ptr);
1128
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1129.SS Unknown-chunk handling
1130
1131Now you get to set the way the library processes unknown chunks in the
1132input PNG stream. Both known and unknown chunks will be read. Normal
1133behavior is that known chunks will be parsed into information in
1134various info_ptr members; unknown chunks will be discarded. To change
1135this, you can call:
1136
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]1137 png_set_keep_unknown_chunks(png_ptr, keep,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1138 chunk_list, num_chunks);
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1139 keep - 0: do not handle as unknown
1140 1: do not keep
1141 2: keep only if safe-to-copy
1142 3: keep even if unsafe-to-copy
1143 You can use these definitions:
1144 PNG_HANDLE_CHUNK_AS_DEFAULT 0
1145 PNG_HANDLE_CHUNK_NEVER 1
1146 PNG_HANDLE_CHUNK_IF_SAFE 2
1147 PNG_HANDLE_CHUNK_ALWAYS 3
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1148 chunk_list - list of chunks affected (a byte string,
1149 five bytes per chunk, NULL or '\0' if
1150 num_chunks is 0)
1151 num_chunks - number of chunks affected; if 0, all
Glenn Randers-Pehrsondff799e2004-08-07 21:42:49 -0500[diff] [blame]1152 unknown chunks are affected. If nonzero,
1153 only the chunks in the list are affected
1154
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1155Unknown chunks declared in this way will be saved as raw data onto a
1156list of png_unknown_chunk structures. If a chunk that is normally
1157known to libpng is named in the list, it will be handled as unknown,
1158according to the "keep" directive. If a chunk is named in successive
1159instances of png_set_keep_unknown_chunks(), the final instance will
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1160take precedence. The IHDR and IEND chunks should not be named in
1161chunk_list; if they are, libpng will process them normally anyway.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1162
1163.SS The high-level read interface
1164
1165At this point there are two ways to proceed; through the high-level
1166read interface, or through a sequence of low-level read operations.
1167You can use the high-level interface if (a) you are willing to read
1168the entire image into memory, and (b) the input transformations
1169you want to do are limited to the following set:
1170
1171 PNG_TRANSFORM_IDENTITY No transformation
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1172 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
1173 8 bits
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1174 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1175 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
1176 samples to bytes
1177 PNG_TRANSFORM_PACKSWAP Change order of packed
1178 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1179 PNG_TRANSFORM_EXPAND Perform set_expand()
1180 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1181 PNG_TRANSFORM_SHIFT Normalize pixels to the
1182 sBIT depth
1183 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
1184 to BGRA
1185 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
1186 to AG
1187 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
1188 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1189 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
1190
1191(This excludes setting a background color, doing gamma transformation,
1192dithering, and setting filler.) If this is the case, simply do this:
1193
1194 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1195
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]1196where png_transforms is an integer containing the bitwise OR of
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1197some set of transformation flags. This call is equivalent to png_read_info(),
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1198followed the set of transformations indicated by the transform mask,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1199then png_read_image(), and finally png_read_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1200
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1201(The final parameter of this call is not yet used. Someday it might point
1202to transformation parameters required by some future input transform.)
1203
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1204You must use png_transforms and not call any png_set_transform() functions
1205when you use png_read_png().
1206
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1207After you have called png_read_png(), you can retrieve the image data
1208with
1209
1210 row_pointers = png_get_rows(png_ptr, info_ptr);
1211
1212where row_pointers is an array of pointers to the pixel data for each row:
1213
1214 png_bytep row_pointers[height];
1215
1216If you know your image size and pixel size ahead of time, you can allocate
1217row_pointers prior to calling png_read_png() with
1218
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]1219 if (height > PNG_UINT_32_MAX/sizeof(png_bytep))
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]1220 png_error (png_ptr,
1221 "Image is too tall to process in memory");
1222 if (width > PNG_UINT_32_MAX/pixel_size)
1223 png_error (png_ptr,
1224 "Image is too wide to process in memory");
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1225 row_pointers = png_malloc(png_ptr,
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]1226 height*sizeof(png_bytep));
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1227 for (int i=0; i<height, i++)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1228 row_pointers[i]=png_malloc(png_ptr,
1229 width*pixel_size);
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]1230 png_set_rows(png_ptr, info_ptr, &row_pointers);
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1231
1232Alternatively you could allocate your image in one big block and define
1233row_pointers[i] to point into the proper places in your block.
1234
1235If you use png_set_rows(), the application is responsible for freeing
1236row_pointers (and row_pointers[i], if they were separately allocated).
1237
1238If you don't allocate row_pointers ahead of time, png_read_png() will
1239do it, and it'll be free'ed when you call png_destroy_*().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1240
1241.SS The low-level read interface
1242
1243If you are going the low-level route, you are now ready to read all
1244the file information up to the actual image data. You do this with a
1245call to png_read_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1246
1247 png_read_info(png_ptr, info_ptr);
1248
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1249This will process all chunks up to but not including the image data.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1250
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1251.SS Querying the info structure
1252
1253Functions are used to get the information from the info_ptr once it
1254has been read. Note that these fields may not be completely filled
1255in until png_read_end() has read the chunk data following the image.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1256
1257 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1258 &bit_depth, &color_type, &interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1259 &compression_type, &filter_method);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1260
1261 width - holds the width of the image
1262 in pixels (up to 2^31).
1263 height - holds the height of the image
1264 in pixels (up to 2^31).
1265 bit_depth - holds the bit depth of one of the
1266 image channels. (valid values are
1267 1, 2, 4, 8, 16 and depend also on
1268 the color_type. See also
1269 significant bits (sBIT) below).
1270 color_type - describes which color/alpha channels
1271 are present.
1272 PNG_COLOR_TYPE_GRAY
1273 (bit depths 1, 2, 4, 8, 16)
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1274 PNG_COLOR_TYPE_GRAY_ALPHA
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1275 (bit depths 8, 16)
1276 PNG_COLOR_TYPE_PALETTE
1277 (bit depths 1, 2, 4, 8)
1278 PNG_COLOR_TYPE_RGB
1279 (bit_depths 8, 16)
1280 PNG_COLOR_TYPE_RGB_ALPHA
1281 (bit_depths 8, 16)
1282
1283 PNG_COLOR_MASK_PALETTE
1284 PNG_COLOR_MASK_COLOR
1285 PNG_COLOR_MASK_ALPHA
1286
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1287 filter_method - (must be PNG_FILTER_TYPE_BASE
1288 for PNG 1.0, and can also be
1289 PNG_INTRAPIXEL_DIFFERENCING if
1290 the PNG datastream is embedded in
1291 a MNG-1.0 datastream)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1292 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1293 for PNG 1.0)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1294 interlace_type - (PNG_INTERLACE_NONE or
1295 PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1296 Any or all of interlace_type, compression_type, of
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1297 filter_method can be NULL if you are
1298 not interested in their values.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1299
1300 channels = png_get_channels(png_ptr, info_ptr);
1301 channels - number of channels of info for the
1302 color type (valid values are 1 (GRAY,
1303 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1304 4 (RGB_ALPHA or RGB + filler byte))
1305 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1306 rowbytes - number of bytes needed to hold a row
1307
1308 signature = png_get_signature(png_ptr, info_ptr);
1309 signature - holds the signature read from the
1310 file (if any). The data is kept in
1311 the same offset it would be if the
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1312 whole signature were read (i.e. if an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1313 application had already read in 4
1314 bytes of signature before starting
1315 libpng, the remaining 4 bytes would
1316 be in signature[4] through signature[7]
1317 (see png_set_sig_bytes())).
1318
1319
1320 width = png_get_image_width(png_ptr,
1321 info_ptr);
1322 height = png_get_image_height(png_ptr,
1323 info_ptr);
1324 bit_depth = png_get_bit_depth(png_ptr,
1325 info_ptr);
1326 color_type = png_get_color_type(png_ptr,
1327 info_ptr);
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1328 filter_method = png_get_filter_type(png_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1329 info_ptr);
1330 compression_type = png_get_compression_type(png_ptr,
1331 info_ptr);
1332 interlace_type = png_get_interlace_type(png_ptr,
1333 info_ptr);
1334
1335
1336These are also important, but their validity depends on whether the chunk
1337has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1338png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1339data has been read, or zero if it is missing. The parameters to the
1340png_get_<chunk> are set directly if they are simple data types, or a pointer
1341into the info_ptr is returned for any complex types.
1342
1343 png_get_PLTE(png_ptr, info_ptr, &palette,
1344 &num_palette);
1345 palette - the palette for the file
1346 (array of png_color)
1347 num_palette - number of entries in the palette
1348
1349 png_get_gAMA(png_ptr, info_ptr, &gamma);
1350 gamma - the gamma the file is written
1351 at (PNG_INFO_gAMA)
1352
1353 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1354 srgb_intent - the rendering intent (PNG_INFO_sRGB)
1355 The presence of the sRGB chunk
1356 means that the pixel data is in the
1357 sRGB color space. This chunk also
1358 implies specific values of gAMA and
1359 cHRM.
1360
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1361 png_get_iCCP(png_ptr, info_ptr, &name,
1362 &compression_type, &profile, &proflen);
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1363 name - The profile name.
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1364 compression - The compression type; always
1365 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1366 You may give NULL to this argument to
1367 ignore it.
1368 profile - International Color Consortium color
1369 profile data. May contain NULs.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1370 proflen - length of profile data in bytes.
1371
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1372 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1373 sig_bit - the number of significant bits for
1374 (PNG_INFO_sBIT) each of the gray,
1375 red, green, and blue channels,
1376 whichever are appropriate for the
1377 given color type (png_color_16)
1378
1379 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
1380 &trans_values);
1381 trans - array of transparent entries for
1382 palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]1383 trans_values - graylevel or color sample values of
1384 the single transparent color for
1385 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1386 num_trans - number of transparent entries
1387 (PNG_INFO_tRNS)
1388
1389 png_get_hIST(png_ptr, info_ptr, &hist);
1390 (PNG_INFO_hIST)
1391 hist - histogram of palette (array of
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1392 png_uint_16)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1393
1394 png_get_tIME(png_ptr, info_ptr, &mod_time);
1395 mod_time - time image was last modified
1396 (PNG_VALID_tIME)
1397
1398 png_get_bKGD(png_ptr, info_ptr, &background);
1399 background - background color (PNG_VALID_bKGD)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1400 valid 16-bit red, green and blue
1401 values, regardless of color_type
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1402
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1403 num_comments = png_get_text(png_ptr, info_ptr,
1404 &text_ptr, &num_text);
1405 num_comments - number of comments
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1406 text_ptr - array of png_text holding image
1407 comments
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1408 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1409 on "text" PNG_TEXT_COMPRESSION_NONE
1410 PNG_TEXT_COMPRESSION_zTXt
1411 PNG_ITXT_COMPRESSION_NONE
1412 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1413 text_ptr[i].key - keyword for comment. Must contain
1414 1-79 characters.
1415 text_ptr[i].text - text comments for current
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1416 keyword. Can be empty.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1417 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1418 after decompression, 0 for iTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1419 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1420 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1421 text_ptr[i].lang - language of comment (empty
1422 string for unknown).
Glenn Randers-Pehrson73d57cb2002-03-25 18:49:08 -0600[diff] [blame]1423 text_ptr[i].lang_key - keyword in UTF-8
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1424 (empty string for unknown).
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1425 num_text - number of comments (same as
1426 num_comments; you can put NULL here
1427 to avoid the duplication)
1428 Note while png_set_text() will accept text, language,
1429 and translated keywords that can be NULL pointers, the
1430 structure returned by png_get_text will always contain
1431 regular zero-terminated C strings. They might be
1432 empty strings but they will never be NULL pointers.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1433
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1434 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1435 &palette_ptr);
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1436 palette_ptr - array of palette structures holding
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1437 contents of one or more sPLT chunks
1438 read.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1439 num_spalettes - number of sPLT chunks read.
1440
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1441 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1442 &unit_type);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1443 offset_x - positive offset from the left edge
1444 of the screen
1445 offset_y - positive offset from the top edge
1446 of the screen
1447 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1448
1449 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1450 &unit_type);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1451 res_x - pixels/unit physical resolution in
1452 x direction
1453 res_y - pixels/unit physical resolution in
1454 x direction
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1455 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1456 PNG_RESOLUTION_METER
1457
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1458 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1459 &height)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1460 unit - physical scale units (an integer)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1461 width - width of a pixel in physical scale units
1462 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1463 (width and height are doubles)
1464
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1465 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1466 &height)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1467 unit - physical scale units (an integer)
1468 width - width of a pixel in physical scale units
1469 height - height of a pixel in physical scale units
1470 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1471
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1472 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1473 info_ptr, &unknowns)
1474 unknowns - array of png_unknown_chunk
1475 structures holding unknown chunks
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1476 unknowns[i].name - name of unknown chunk
1477 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1478 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1479 unknowns[i].location - position of chunk in file
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1480
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1481 The value of "i" corresponds to the order in which the
1482 chunks were read from the PNG file or inserted with the
1483 png_set_unknown_chunks() function.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1484
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1485The data from the pHYs chunk can be retrieved in several convenient
1486forms:
1487
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1488 res_x = png_get_x_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1489 info_ptr)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1490 res_y = png_get_y_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1491 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1492 res_x_and_y = png_get_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1493 info_ptr)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1494 res_x = png_get_x_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1495 info_ptr)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1496 res_y = png_get_y_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1497 info_ptr)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1498 res_x_and_y = png_get_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1499 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1500 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1501 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1502
1503 (Each of these returns 0 [signifying "unknown"] if
1504 the data is not present or if res_x is 0;
1505 res_x_and_y is 0 if res_x != res_y)
1506
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1507The data from the oFFs chunk can be retrieved in several convenient
1508forms:
1509
1510 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1511 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1512 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1513 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1514
1515 (Each of these returns 0 [signifying "unknown" if both
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1516 x and y are 0] if the data is not present or if the
1517 chunk is present but the unit is the pixel)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1518
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1519For more information, see the png_info definition in png.h and the
1520PNG specification for chunk contents. Be careful with trusting
1521rowbytes, as some of the transformations could increase the space
1522needed to hold a row (expand, filler, gray_to_rgb, etc.).
1523See png_read_update_info(), below.
1524
1525A quick word about text_ptr and num_text. PNG stores comments in
1526keyword/text pairs, one pair per chunk, with no limit on the number
1527of text chunks, and a 2^31 byte limit on their size. While there are
1528suggested keywords, there is no requirement to restrict the use to these
1529strings. It is strongly suggested that keywords and text be sensible
1530to humans (that's the point), so don't use abbreviations. Non-printing
1531symbols are not allowed. See the PNG specification for more details.
1532There is also no requirement to have text after the keyword.
1533
1534Keywords should be limited to 79 Latin-1 characters without leading or
1535trailing spaces, but non-consecutive spaces are allowed within the
1536keyword. It is possible to have the same keyword any number of times.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1537The text_ptr is an array of png_text structures, each holding a
1538pointer to a language string, a pointer to a keyword and a pointer to
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1539a text string. The text string, language code, and translated
1540keyword may be empty or NULL pointers. The keyword/text
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1541pairs are put into the array in the order that they are received.
1542However, some or all of the text chunks may be after the image, so, to
1543make sure you have read all the text chunks, don't mess with these
1544until after you read the stuff after the image. This will be
1545mentioned again below in the discussion that goes with png_read_end().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1546
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1547.SS Input transformations
1548
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1549After you've read the header information, you can set up the library
1550to handle any special transformations of the image data. The various
1551ways to transform the data will be described in the order that they
1552should occur. This is important, as some of these change the color
1553type and/or bit depth of the data, and some others only work on
1554certain color types and bit depths. Even though each transformation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1555checks to see if it has data that it can do something with, you should
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1556make sure to only enable a transformation if it will be valid for the
1557data. For example, don't swap red and blue on grayscale data.
1558
1559The colors used for the background and transparency values should be
1560supplied in the same format/depth as the current image data. They
1561are stored in the same format/depth as the image data in a bKGD or tRNS
1562chunk, so this is what libpng expects for this data. The colors are
1563transformed to keep in sync with the image data when an application
1564calls the png_read_update_info() routine (see below).
1565
1566Data will be decoded into the supplied row buffers packed into bytes
1567unless the library has been told to transform it into another format.
1568For example, 4 bit/pixel paletted or grayscale data will be returned
15692 pixels/byte with the leftmost pixel in the high-order bits of the
1570byte, unless png_set_packing() is called. 8-bit RGB data will be stored
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1571in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
1572is called to insert filler bytes, either before or after each RGB triplet.
157316-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
1574byte of the color value first, unless png_set_strip_16() is called to
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]1575transform it to regular RGB RGB triplets, or png_set_filler() or
1576png_set_add alpha() is called to insert filler bytes, either before or
1577after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
1578be modified with
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1579png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1580
1581The following code transforms grayscale images of less than 8 to 8 bits,
1582changes paletted images to RGB, and adds a full alpha channel if there is
1583transparency information in a tRNS chunk. This is most useful on
1584grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1585viewing application that wishes to treat all images in the same way.
1586
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1587 if (color_type == PNG_COLOR_TYPE_PALETTE)
1588 png_set_palette_to_rgb(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1589
1590 if (color_type == PNG_COLOR_TYPE_GRAY &&
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]1591 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1592
1593 if (png_get_valid(png_ptr, info_ptr,
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1594 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1595
1596These three functions are actually aliases for png_set_expand(), added
1597in libpng version 1.0.4, with the function names expanded to improve code
1598readability. In some future version they may actually do different
1599things.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1600
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]1601As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
1602added. It expands the sample depth without changing tRNS to alpha.
Glenn Randers-Pehrsoneb580912008-07-30 14:47:09 -0500[diff] [blame]1603%12%At the same time, png_set_gray_1_2_4_to_8() was deprecated, and it
1604%12%will be removed from a future version.
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]1605
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1606PNG can have files with 16 bits per channel. If you only can handle
16078 bits per channel, this will strip the pixels down to 8 bit.
1608
1609 if (bit_depth == 16)
1610 png_set_strip_16(png_ptr);
1611
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1612If, for some reason, you don't need the alpha channel on an image,
1613and you want to remove it rather than combining it with the background
1614(but the image author certainly had in mind that you *would* combine
1615it with the background, so that's what you should probably do):
1616
1617 if (color_type & PNG_COLOR_MASK_ALPHA)
1618 png_set_strip_alpha(png_ptr);
1619
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1620In PNG files, the alpha channel in an image
1621is the level of opacity. If you need the alpha channel in an image to
1622be the level of transparency instead of opacity, you can invert the
1623alpha channel (or the tRNS chunk data) after it's read, so that 0 is
1624fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
1625images) is fully transparent, with
1626
1627 png_set_invert_alpha(png_ptr);
1628
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]1629The PNG format only supports pixels with postmultiplied alpha.
1630If you want to replace the pixels, after reading them, with pixels
1631that have premultiplied color samples, you can do this with
1632
1633 png_set_premultiply_alpha(png_ptr);
1634
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1635PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1636they can, resulting in, for example, 8 pixels per byte for 1 bit
1637files. This code expands to 1 pixel per byte without changing the
1638values of the pixels:
1639
1640 if (bit_depth < 8)
1641 png_set_packing(png_ptr);
1642
1643PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1644stored in a PNG image have been "scaled" or "shifted" up to the next
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1645higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]16468 bits/sample in the range [0, 255]). However, it is also possible to
1647convert the PNG pixel data back to the original bit depth of the image.
1648This call reduces the pixels back down to the original bit depth:
1649
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]1650 png_color_8p sig_bit;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1651
1652 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1653 png_set_shift(png_ptr, sig_bit);
1654
1655PNG files store 3-color pixels in red, green, blue order. This code
1656changes the storage of the pixels to blue, green, red:
1657
1658 if (color_type == PNG_COLOR_TYPE_RGB ||
1659 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1660 png_set_bgr(png_ptr);
1661
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]1662PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
1663into 4 or 8 bytes for windowing systems that need them in this format:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1664
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]1665 if (color_type == PNG_COLOR_TYPE_RGB)
1666 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1667
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]1668where "filler" is the 8 or 16-bit number to fill with, and the location is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1669either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1670you want the filler before the RGB or after. This transformation
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]1671does not affect images that already have full alpha channels. To add an
1672opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
1673will generate RGBA pixels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1674
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1675Note that png_set_filler() does not change the color type. If you want
1676to do that, you can add a true alpha channel with
1677
1678 if (color_type == PNG_COLOR_TYPE_RGB ||
1679 color_type == PNG_COLOR_TYPE_GRAY)
1680 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1681
1682where "filler" contains the alpha value to assign to each pixel.
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]1683This function was added in libpng-1.2.7.
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1684
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1685If you are reading an image with an alpha channel, and you need the
1686data as ARGB instead of the normal PNG format RGBA:
1687
1688 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1689 png_set_swap_alpha(png_ptr);
1690
1691For some uses, you may want a grayscale image to be represented as
1692RGB. This code will do that conversion:
1693
1694 if (color_type == PNG_COLOR_TYPE_GRAY ||
1695 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1696 png_set_gray_to_rgb(png_ptr);
1697
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1698Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1699with alpha.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1700
1701 if (color_type == PNG_COLOR_TYPE_RGB ||
1702 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1703 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1704 int red_weight, int green_weight);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1705
1706 error_action = 1: silently do the conversion
1707 error_action = 2: issue a warning if the original
1708 image has any pixel where
1709 red != green or red != blue
1710 error_action = 3: issue an error and abort the
1711 conversion if the original
1712 image has any pixel where
1713 red != green or red != blue
1714
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1715 red_weight: weight of red component times 100000
1716 green_weight: weight of green component times 100000
1717 If either weight is negative, default
1718 weights (21268, 71514) are used.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1719
1720If you have set error_action = 1 or 2, you can
1721later check whether the image really was gray, after processing
1722the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1723It will return a png_byte that is zero if the image was gray or
17241 if there were any non-gray pixels. bKGD and sBIT data
1725will be silently converted to grayscale, using the green channel
1726data, regardless of the error_action setting.
1727
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1728With red_weight+green_weight<=100000,
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1729the normalized graylevel is computed:
1730
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1731 int rw = red_weight * 65536;
1732 int gw = green_weight * 65536;
1733 int bw = 65536 - (rw + gw);
1734 gray = (rw*red + gw*green + bw*blue)/65536;
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1735
1736The default values approximate those recommended in the Charles
1737Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]1738Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1739
1740 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1741
1742Libpng approximates this with
1743
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1744 Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1745
1746which can be expressed with integers as
1747
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1748 Y = (6969 * R + 23434 * G + 2365 * B)/32768
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1749
1750The calculation is done in a linear colorspace, if the image gamma
1751is known.
1752
Glenn Randers-Pehrson73d57cb2002-03-25 18:49:08 -0600[diff] [blame]1753If you have a grayscale and you are using png_set_expand_depth(),
1754png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]1755a higher bit-depth, you must either supply the background color as a gray
1756value at the original file bit-depth (need_expand = 1) or else supply the
1757background color as an RGB triplet at the final, expanded bit depth
1758(need_expand = 0). Similarly, if you are reading a paletted image, you
1759must either supply the background color as a palette index (need_expand = 1)
1760or as an RGB triplet that may or may not be in the palette (need_expand = 0).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1761
1762 png_color_16 my_background;
1763 png_color_16p image_background;
1764
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]1765 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1766 png_set_background(png_ptr, image_background,
1767 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1768 else
1769 png_set_background(png_ptr, &my_background,
1770 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1771
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1772The png_set_background() function tells libpng to composite images
1773with alpha or simple transparency against the supplied background
1774color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1775you may use this color, or supply another color more suitable for
1776the current display (e.g., the background color from a web page). You
1777need to tell libpng whether the color is in the gamma space of the
1778display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
1779(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
1780that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
1781know why anyone would use this, but it's here).
1782
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1783To properly display PNG images on any kind of system, the application needs
1784to know what the display gamma is. Ideally, the user will know this, and
1785the application will allow them to set it. One method of allowing the user
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]1786to set the display gamma separately for each system is to check for a
1787SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
1788correctly set.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1789
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]1790Note that display_gamma is the overall gamma correction required to produce
1791pleasing results, which depends on the lighting conditions in the surrounding
1792environment. In a dim or brightly lit room, no compensation other than
1793the physical gamma exponent of the monitor is needed, while in a dark room
1794a slightly smaller exponent is better.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1795
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1796 double gamma, screen_gamma;
1797
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1798 if (/* We have a user-defined screen
1799 gamma value */)
1800 {
1801 screen_gamma = user_defined_screen_gamma;
1802 }
1803 /* One way that applications can share the same
1804 screen gamma value */
1805 else if ((gamma_str = getenv("SCREEN_GAMMA"))
1806 != NULL)
1807 {
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1808 screen_gamma = (double)atof(gamma_str);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1809 }
1810 /* If we don't have another value */
1811 else
1812 {
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1813 screen_gamma = 2.2; /* A good guess for a
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1814 PC monitor in a bright office or a dim room */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1815 screen_gamma = 2.0; /* A good guess for a
1816 PC monitor in a dark room */
1817 screen_gamma = 1.7 or 1.0; /* A good
1818 guess for Mac systems */
1819 }
1820
1821The png_set_gamma() function handles gamma transformations of the data.
1822Pass both the file gamma and the current screen_gamma. If the file does
1823not have a gamma value, you can pass one anyway if you have an idea what
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1824it is (usually 0.45455 is a good guess for GIF images on PCs). Note
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1825that file gammas are inverted from screen gammas. See the discussions
1826on gamma in the PNG specification for an excellent description of what
1827gamma is, and why all applications should support it. It is strongly
1828recommended that PNG viewers support gamma correction.
1829
1830 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1831 png_set_gamma(png_ptr, screen_gamma, gamma);
1832 else
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1833 png_set_gamma(png_ptr, screen_gamma, 0.45455);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1834
1835If you need to reduce an RGB file to a paletted file, or if a paletted
1836file has more entries then will fit on your screen, png_set_dither()
1837will do that. Note that this is a simple match dither that merely
1838finds the closest color available. This should work fairly well with
1839optimized palettes, and fairly badly with linear color cubes. If you
1840pass a palette that is larger then maximum_colors, the file will
1841reduce the number of colors in the palette so it will fit into
1842maximum_colors. If there is a histogram, it will use it to make
1843more intelligent choices when reducing the palette. If there is no
1844histogram, it may not do as good a job.
1845
1846 if (color_type & PNG_COLOR_MASK_COLOR)
1847 {
1848 if (png_get_valid(png_ptr, info_ptr,
1849 PNG_INFO_PLTE))
1850 {
Glenn Randers-Pehrson865f4f02002-09-15 20:30:38 -0500[diff] [blame]1851 png_uint_16p histogram = NULL;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1852
1853 png_get_hIST(png_ptr, info_ptr,
1854 &histogram);
1855 png_set_dither(png_ptr, palette, num_palette,
1856 max_screen_colors, histogram, 1);
1857 }
1858 else
1859 {
1860 png_color std_color_cube[MAX_SCREEN_COLORS] =
1861 { ... colors ... };
1862
1863 png_set_dither(png_ptr, std_color_cube,
1864 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1865 NULL,0);
1866 }
1867 }
1868
1869PNG files describe monochrome as black being zero and white being one.
1870The following code will reverse this (make black be one and white be
1871zero):
1872
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]1873 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1874 png_set_invert_mono(png_ptr);
1875
1876This function can also be used to invert grayscale and gray-alpha images:
1877
1878 if (color_type == PNG_COLOR_TYPE_GRAY ||
1879 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1880 png_set_invert_mono(png_ptr);
1881
1882PNG files store 16 bit pixels in network byte order (big-endian,
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1883ie. most significant bits first). This code changes the storage to the
1884other way (little-endian, i.e. least significant bits first, the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1885way PCs store them):
1886
1887 if (bit_depth == 16)
1888 png_set_swap(png_ptr);
1889
1890If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1891need to change the order the pixels are packed into bytes, you can use:
1892
1893 if (bit_depth < 8)
1894 png_set_packswap(png_ptr);
1895
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1896Finally, you can write your own transformation function if none of
1897the existing ones meets your needs. This is done by setting a callback
1898with
1899
1900 png_set_read_user_transform_fn(png_ptr,
1901 read_transform_fn);
1902
1903You must supply the function
1904
1905 void read_transform_fn(png_ptr ptr, row_info_ptr
1906 row_info, png_bytep data)
1907
1908See pngtest.c for a working example. Your function will be called
1909after all of the other transformations have been processed.
1910
1911You can also set up a pointer to a user structure for use by your
1912callback function, and you can inform libpng that your transform
1913function will change the number of channels or bit depth with the
1914function
1915
1916 png_set_user_transform_info(png_ptr, user_ptr,
1917 user_depth, user_channels);
1918
1919The user's application, not libpng, is responsible for allocating and
1920freeing any memory required for the user structure.
1921
1922You can retrieve the pointer via the function
1923png_get_user_transform_ptr(). For example:
1924
1925 voidp read_user_transform_ptr =
1926 png_get_user_transform_ptr(png_ptr);
1927
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1928The last thing to handle is interlacing; this is covered in detail below,
1929but you must call the function here if you want libpng to handle expansion
1930of the interlaced image.
1931
1932 number_of_passes = png_set_interlace_handling(png_ptr);
1933
1934After setting the transformations, libpng can update your png_info
1935structure to reflect any transformations you've requested with this
1936call. This is most useful to update the info structure's rowbytes
1937field so you can use it to allocate your image memory. This function
1938will also update your palette with the correct screen_gamma and
1939background if these have been given with the calls above.
1940
1941 png_read_update_info(png_ptr, info_ptr);
1942
1943After you call png_read_update_info(), you can allocate any
1944memory you need to hold the image. The row data is simply
1945raw byte data for all forms of images. As the actual allocation
1946varies among applications, no example will be given. If you
1947are allocating one large chunk, you will need to build an
1948array of pointers to each row, as it will be needed for some
1949of the functions below.
1950
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1951.SS Reading image data
1952
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1953After you've allocated memory, you can read the image data.
1954The simplest way to do this is in one function call. If you are
1955allocating enough memory to hold the whole image, you can just
1956call png_read_image() and libpng will read in all the image data
1957and put it in the memory area supplied. You will need to pass in
1958an array of pointers to each row.
1959
1960This function automatically handles interlacing, so you don't need
1961to call png_set_interlace_handling() or call this function multiple
1962times, or any of that other stuff necessary with png_read_rows().
1963
1964 png_read_image(png_ptr, row_pointers);
1965
1966where row_pointers is:
1967
1968 png_bytep row_pointers[height];
1969
1970You can point to void or char or whatever you use for pixels.
1971
1972If you don't want to read in the whole image at once, you can
1973use png_read_rows() instead. If there is no interlacing (check
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1974interlace_type == PNG_INTERLACE_NONE), this is simple:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1975
1976 png_read_rows(png_ptr, row_pointers, NULL,
1977 number_of_rows);
1978
1979where row_pointers is the same as in the png_read_image() call.
1980
1981If you are doing this just one row at a time, you can do this with
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1982a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1983
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1984 png_bytep row_pointer = row;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1985 png_read_row(png_ptr, row_pointer, NULL);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1986
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1987If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1988get somewhat harder. The only current (PNG Specification version 1.2)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1989interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1990is a somewhat complicated 2D interlace scheme, known as Adam7, that
1991breaks down an image into seven smaller images of varying size, based
1992on an 8x8 grid.
1993
1994libpng can fill out those images or it can give them to you "as is".
1995If you want them filled out, there are two ways to do that. The one
1996mentioned in the PNG specification is to expand each pixel to cover
1997those pixels that have not been read yet (the "rectangle" method).
1998This results in a blocky image for the first pass, which gradually
1999smooths out as more pixels are read. The other method is the "sparkle"
2000method, where pixels are drawn only in their final locations, with the
2001rest of the image remaining whatever colors they were initialized to
2002before the start of the read. The first method usually looks better,
2003but tends to be slower, as there are more pixels to put in the rows.
2004
2005If you don't want libpng to handle the interlacing details, just call
2006png_read_rows() seven times to read in all seven images. Each of the
2007images is a valid image by itself, or they can all be combined on an
20088x8 grid to form a single image (although if you intend to combine them
2009you would be far better off using the libpng interlace handling).
2010
2011The first pass will return an image 1/8 as wide as the entire image
2012(every 8th column starting in column 0) and 1/8 as high as the original
2013(every 8th row starting in row 0), the second will be 1/8 as wide
2014(starting in column 4) and 1/8 as high (also starting in row 0). The
2015third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
20161/8 as high (every 8th row starting in row 4), and the fourth pass will
2017be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
2018and every 4th row starting in row 0). The fifth pass will return an
2019image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
2020while the sixth pass will be 1/2 as wide and 1/2 as high as the original
2021(starting in column 1 and row 0). The seventh and final pass will be as
2022wide as the original, and 1/2 as high, containing all of the odd
2023numbered scanlines. Phew!
2024
2025If you want libpng to expand the images, call this before calling
2026png_start_read_image() or png_read_update_info():
2027
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2028 if (interlace_type == PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2029 number_of_passes
2030 = png_set_interlace_handling(png_ptr);
2031
2032This will return the number of passes needed. Currently, this
2033is seven, but may change if another interlace type is added.
2034This function can be called even if the file is not interlaced,
2035where it will return one pass.
2036
2037If you are not going to display the image after each pass, but are
2038going to wait until the entire image is read in, use the sparkle
2039effect. This effect is faster and the end result of either method
2040is exactly the same. If you are planning on displaying the image
2041after each pass, the "rectangle" effect is generally considered the
2042better looking one.
2043
2044If you only want the "sparkle" effect, just call png_read_rows() as
2045normal, with the third parameter NULL. Make sure you make pass over
2046the image number_of_passes times, and you don't change the data in the
2047rows between calls. You can change the locations of the data, just
2048not the data. Each pass only writes the pixels appropriate for that
2049pass, and assumes the data from previous passes is still valid.
2050
2051 png_read_rows(png_ptr, row_pointers, NULL,
2052 number_of_rows);
2053
2054If you only want the first effect (the rectangles), do the same as
2055before except pass the row buffer in the third parameter, and leave
2056the second parameter NULL.
2057
2058 png_read_rows(png_ptr, NULL, row_pointers,
2059 number_of_rows);
2060
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2061.SS Finishing a sequential read
2062
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]2063After you are finished reading the image through the
2064low-level interface, you can finish reading the file. If you are
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2065interested in comments or time, which may be stored either before or
2066after the image data, you should pass the separate png_info struct if
2067you want to keep the comments from before and after the image
2068separate. If you are not interested, you can pass NULL.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2069
2070 png_read_end(png_ptr, end_info);
2071
2072When you are done, you can free all memory allocated by libpng like this:
2073
2074 png_destroy_read_struct(&png_ptr, &info_ptr,
2075 &end_info);
2076
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2077It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2078point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2079
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2080 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2081 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2082 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2083 more of
2084 PNG_FREE_PLTE, PNG_FREE_TRNS,
2085 PNG_FREE_HIST, PNG_FREE_ICCP,
2086 PNG_FREE_PCAL, PNG_FREE_ROWS,
2087 PNG_FREE_SCAL, PNG_FREE_SPLT,
2088 PNG_FREE_TEXT, PNG_FREE_UNKN,
2089 or simply PNG_FREE_ALL
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2090 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2091 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2092
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2093This function may be safely called when the relevant storage has
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]2094already been freed, or has not yet been allocated, or was allocated
2095by the user and not by libpng, and will in those
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2096cases do nothing. The "seq" parameter is ignored if only one item
2097of the selected data type, such as PLTE, is allowed. If "seq" is not
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2098-1, and multiple items are allowed for the data type identified in
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2099the mask, such as text or sPLT, only the n'th item in the structure
2100is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2101
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2102The default behavior is only to free data that was allocated internally
2103by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2104or so that it will free data that was allocated by the user with png_malloc()
2105or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2106
2107 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2108 mask - which data elements are affected
2109 same choices as in png_free_data()
2110 freer - one of
2111 PNG_DESTROY_WILL_FREE_DATA
2112 PNG_SET_WILL_FREE_DATA
2113 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2114
2115This function only affects data that has already been allocated.
2116You can call this function after reading the PNG data but before calling
2117any png_set_*() functions, to control whether the user or the png_set_*()
2118function is responsible for freeing any existing data that might be present,
2119and again after the png_set_*() functions to control whether the user
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2120or png_destroy_*() is supposed to free the data. When the user assumes
2121responsibility for libpng-allocated data, the application must use
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2122png_free() to free it, and when the user transfers responsibility to libpng
2123for data that the user has allocated, the user must have used png_malloc()
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]2124or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2125
2126If you allocated your row_pointers in a single block, as suggested above in
2127the description of the high level read interface, you must not transfer
2128responsibility for freeing it to the png_set_rows or png_read_destroy function,
2129because they would also try to free the individual row_pointers[i].
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2130
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2131If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2132separately, do not transfer responsibility for freeing text_ptr to libpng,
2133because when libpng fills a png_text structure it combines these members with
2134the key member, and png_free_data() will free only text_ptr.key. Similarly,
2135if you transfer responsibility for free'ing text_ptr from libpng to your
2136application, your application must not separately free those members.
2137
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2138The png_free_data() function will turn off the "valid" flag for anything
2139it frees. If you need to turn the flag off for a chunk that was freed by your
2140application instead of by libpng, you can use
2141
2142 png_set_invalid(png_ptr, info_ptr, mask);
2143 mask - identifies the chunks to be made invalid,
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2144 containing the bitwise OR of one or
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]2145 more of
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2146 PNG_INFO_gAMA, PNG_INFO_sBIT,
2147 PNG_INFO_cHRM, PNG_INFO_PLTE,
2148 PNG_INFO_tRNS, PNG_INFO_bKGD,
2149 PNG_INFO_hIST, PNG_INFO_pHYs,
2150 PNG_INFO_oFFs, PNG_INFO_tIME,
2151 PNG_INFO_pCAL, PNG_INFO_sRGB,
2152 PNG_INFO_iCCP, PNG_INFO_sPLT,
2153 PNG_INFO_sCAL, PNG_INFO_IDAT
2154
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2155For a more compact example of reading a PNG image, see the file example.c.
2156
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2157.SS Reading PNG files progressively
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2158
2159The progressive reader is slightly different then the non-progressive
2160reader. Instead of calling png_read_info(), png_read_rows(), and
2161png_read_end(), you make one call to png_process_data(), which calls
2162callbacks when it has the info, a row, or the end of the image. You
2163set up these callbacks with png_set_progressive_read_fn(). You don't
2164have to worry about the input/output functions of libpng, as you are
2165giving the library the data directly in png_process_data(). I will
2166assume that you have read the section on reading PNG files above,
2167so I will only highlight the differences (although I will show
2168all of the code).
2169
2170png_structp png_ptr;
2171png_infop info_ptr;
2172
2173 /* An example code fragment of how you would
2174 initialize the progressive reader in your
2175 application. */
2176 int
2177 initialize_png_reader()
2178 {
2179 png_ptr = png_create_read_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]2180 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2181 user_error_fn, user_warning_fn);
2182 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2183 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2184 info_ptr = png_create_info_struct(png_ptr);
2185 if (!info_ptr)
2186 {
2187 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
2188 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2189 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2190 }
2191
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2192 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2193 {
2194 png_destroy_read_struct(&png_ptr, &info_ptr,
2195 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2196 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2197 }
2198
2199 /* This one's new. You can provide functions
2200 to be called when the header info is valid,
2201 when each row is completed, and when the image
2202 is finished. If you aren't using all functions,
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2203 you can specify NULL parameters. Even when all
2204 three functions are NULL, you need to call
2205 png_set_progressive_read_fn(). You can use
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2206 any struct as the user_ptr (cast to a void pointer
2207 for the function call), and retrieve the pointer
2208 from inside the callbacks using the function
2209
2210 png_get_progressive_ptr(png_ptr);
2211
2212 which will return a void pointer, which you have
2213 to cast appropriately.
2214 */
2215 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2216 info_callback, row_callback, end_callback);
2217
2218 return 0;
2219 }
2220
2221 /* A code fragment that you call as you receive blocks
2222 of data */
2223 int
2224 process_data(png_bytep buffer, png_uint_32 length)
2225 {
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2226 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2227 {
2228 png_destroy_read_struct(&png_ptr, &info_ptr,
2229 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2230 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2231 }
2232
2233 /* This one's new also. Simply give it a chunk
2234 of data from the file stream (in order, of
2235 course). On machines with segmented memory
2236 models machines, don't give it any more than
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2237 64K. The library seems to run fine with sizes
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2238 of 4K. Although you can give it much less if
2239 necessary (I assume you can give it chunks of
2240 1 byte, I haven't tried less then 256 bytes
2241 yet). When this function returns, you may
2242 want to display any rows that were generated
2243 in the row callback if you don't already do
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2244 so there.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2245 */
2246 png_process_data(png_ptr, info_ptr, buffer, length);
2247 return 0;
2248 }
2249
2250 /* This function is called (as set by
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2251 png_set_progressive_read_fn() above) when enough data
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2252 has been supplied so all of the header has been
2253 read.
2254 */
2255 void
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2256 info_callback(png_structp png_ptr, png_infop info)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2257 {
2258 /* Do any setup here, including setting any of
2259 the transformations mentioned in the Reading
2260 PNG files section. For now, you _must_ call
2261 either png_start_read_image() or
2262 png_read_update_info() after all the
2263 transformations are set (even if you don't set
2264 any). You may start getting rows before
2265 png_process_data() returns, so this is your
2266 last chance to prepare for that.
2267 */
2268 }
2269
2270 /* This function is called when each row of image
2271 data is complete */
2272 void
2273 row_callback(png_structp png_ptr, png_bytep new_row,
Glenn Randers-Pehrsone68f5a32001-05-14 09:20:53 -0500[diff] [blame]2274 png_uint_32 row_num, int pass)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2275 {
2276 /* If the image is interlaced, and you turned
2277 on the interlace handler, this function will
2278 be called for every row in every pass. Some
2279 of these rows will not be changed from the
2280 previous pass. When the row is not changed,
2281 the new_row variable will be NULL. The rows
2282 and passes are called in order, so you don't
2283 really need the row_num and pass, but I'm
2284 supplying them because it may make your life
2285 easier.
2286
2287 For the non-NULL rows of interlaced images,
2288 you must call png_progressive_combine_row()
2289 passing in the row and the old row. You can
2290 call this function for NULL rows (it will just
2291 return) and for non-interlaced images (it just
2292 does the memcpy for you) if it will make the
2293 code easier. Thus, you can just do this for
2294 all cases:
2295 */
2296
2297 png_progressive_combine_row(png_ptr, old_row,
2298 new_row);
2299
2300 /* where old_row is what was displayed for
Glenn Randers-Pehrson345bc271998-06-14 14:43:31 -0500[diff] [blame]2301 previously for the row. Note that the first
2302 pass (pass == 0, really) will completely cover
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2303 the old row, so the rows do not have to be
2304 initialized. After the first pass (and only
2305 for interlaced images), you will have to pass
2306 the current row, and the function will combine
2307 the old row and the new row.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2308 */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2309 }
2310
2311 void
2312 end_callback(png_structp png_ptr, png_infop info)
2313 {
2314 /* This function is called after the whole image
2315 has been read, including any chunks after the
2316 image (up to and including the IEND). You
2317 will usually have the same info chunk as you
2318 had in the header, although some data may have
2319 been added to the comments and time fields.
2320
2321 Most people won't do much here, perhaps setting
2322 a flag that marks the image as finished.
2323 */
2324 }
2325
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2326
2327
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2328.SH IV. Writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2329
2330Much of this is very similar to reading. However, everything of
2331importance is repeated here, so you won't have to constantly look
2332back up in the reading section to understand writing.
2333
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2334.SS Setup
2335
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2336You will want to do the I/O initialization before you get into libpng,
2337so if it doesn't work, you don't have anything to undo. If you are not
2338using the standard I/O functions, you will need to replace them with
2339custom writing functions. See the discussion under Customizing libpng.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2340
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2341 FILE *fp = fopen(file_name, "wb");
2342 if (!fp)
2343 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2344 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2345 }
2346
2347Next, png_struct and png_info need to be allocated and initialized.
2348As these can be both relatively large, you may not want to store these
2349on the stack, unless you have stack space to spare. Of course, you
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2350will want to check if they return NULL. If you are also reading,
2351you won't want to name your read structure and your write structure
2352both "png_ptr"; you can call them anything you like, such as
2353"read_ptr" and "write_ptr". Look at pngtest.c, for example.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2354
2355 png_structp png_ptr = png_create_write_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]2356 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2357 user_error_fn, user_warning_fn);
2358 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2359 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2360
2361 png_infop info_ptr = png_create_info_struct(png_ptr);
2362 if (!info_ptr)
2363 {
2364 png_destroy_write_struct(&png_ptr,
2365 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2366 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2367 }
2368
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]2369If you want to use your own memory allocation routines,
2370define PNG_USER_MEM_SUPPORTED and use
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2371png_create_write_struct_2() instead of png_create_write_struct():
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]2372
2373 png_structp png_ptr = png_create_write_struct_2
2374 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2375 user_error_fn, user_warning_fn, (png_voidp)
2376 user_mem_ptr, user_malloc_fn, user_free_fn);
2377
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2378After you have these structures, you will need to set up the
2379error handling. When libpng encounters an error, it expects to
2380longjmp() back to your routine. Therefore, you will need to call
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2381setjmp() and pass the png_jmpbuf(png_ptr). If you
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2382write the file from different routines, you will need to update
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2383the png_jmpbuf(png_ptr) every time you enter a new routine that will
2384call a png_*() function. See your documentation of setjmp/longjmp
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2385for your compiler for more information on setjmp/longjmp. See
2386the discussion on libpng error handling in the Customizing Libpng
2387section below for more information on the libpng error handling.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2388
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2389 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2390 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2391 png_destroy_write_struct(&png_ptr, &info_ptr);
2392 fclose(fp);
2393 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2394 }
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2395 ...
2396 return;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2397
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2398If you would rather avoid the complexity of setjmp/longjmp issues,
2399you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
2400errors will result in a call to PNG_ABORT() which defaults to abort().
2401
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2402Now you need to set up the output code. The default for libpng is to
2403use the C function fwrite(). If you use this, you will need to pass a
2404valid FILE * in the function png_init_io(). Be sure that the file is
2405opened in binary mode. Again, if you wish to handle writing data in
2406another way, see the discussion on libpng I/O handling in the Customizing
2407Libpng section below.
2408
2409 png_init_io(png_ptr, fp);
2410
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]2411If you are embedding your PNG into a datastream such as MNG, and don't
2412want libpng to write the 8-byte signature, or if you have already
2413written the signature in your application, use
2414
2415 png_set_sig_bytes(png_ptr, 8);
2416
2417to inform libpng that it should not write a signature.
2418
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2419.SS Write callbacks
2420
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2421At this point, you can set up a callback function that will be
2422called after each row has been written, which you can use to control
2423a progress meter or the like. It's demonstrated in pngtest.c.
2424You must supply a function
2425
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2426 void write_row_callback(png_ptr, png_uint_32 row,
2427 int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2428 {
2429 /* put your code here */
2430 }
2431
2432(You can give it another name that you like instead of "write_row_callback")
2433
2434To inform libpng about your function, use
2435
2436 png_set_write_status_fn(png_ptr, write_row_callback);
2437
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2438You now have the option of modifying how the compression library will
2439run. The following functions are mainly for testing, but may be useful
2440in some cases, like if you need to write PNG files extremely fast and
2441are willing to give up some compression, or if you want to get the
2442maximum possible compression at the expense of slower writing. If you
2443have no special needs in this area, let the library do what it wants by
2444not calling this function at all, as it has been tuned to deliver a good
2445speed/compression ratio. The second parameter to png_set_filter() is
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2446the filter method, for which the only valid values are 0 (as of the
2447July 1999 PNG specification, version 1.2) or 64 (if you are writing
2448a PNG datastream that is to be embedded in a MNG datastream). The third
2449parameter is a flag that indicates which filter type(s) are to be tested
2450for each scanline. See the PNG specification for details on the specific filter
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2451types.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2452
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2453
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2454 /* turn on or off filtering, and/or choose
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2455 specific filters. You can use either a single
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2456 PNG_FILTER_VALUE_NAME or the bitwise OR of one
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2457 or more PNG_FILTER_NAME masks. */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2458 png_set_filter(png_ptr, 0,
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2459 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
2460 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
2461 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
2462 PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE |
2463 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2464 PNG_ALL_FILTERS);
2465
2466If an application
2467wants to start and stop using particular filters during compression,
2468it should start out with all of the filters (to ensure that the previous
2469row of pixels will be stored in case it's needed later), and then add
2470and remove them after the start of compression.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2471
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2472If you are writing a PNG datastream that is to be embedded in a MNG
2473datastream, the second parameter can be either 0 or 64.
2474
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2475The png_set_compression_*() functions interface to the zlib compression
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2476library, and should mostly be ignored unless you really know what you are
2477doing. The only generally useful call is png_set_compression_level()
2478which changes how much time zlib spends on trying to compress the image
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2479data. See the Compression Library (zlib.h and algorithm.txt, distributed
2480with zlib) for details on the compression levels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2481
2482 /* set the zlib compression level */
2483 png_set_compression_level(png_ptr,
2484 Z_BEST_COMPRESSION);
2485
2486 /* set other zlib parameters */
2487 png_set_compression_mem_level(png_ptr, 8);
2488 png_set_compression_strategy(png_ptr,
2489 Z_DEFAULT_STRATEGY);
2490 png_set_compression_window_bits(png_ptr, 15);
2491 png_set_compression_method(png_ptr, 8);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2492 png_set_compression_buffer_size(png_ptr, 8192)
2493
2494extern PNG_EXPORT(void,png_set_zbuf_size)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2495
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2496.SS Setting the contents of info for output
2497
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2498You now need to fill in the png_info structure with all the data you
2499wish to write before the actual image. Note that the only thing you
2500are allowed to write after the image is the text chunks and the time
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2501chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2502the latest PNG specification for more information on that. If you
2503wish to write them before the image, fill them in now, and flag that
2504data as being valid. If you want to wait until after the data, don't
2505fill them until png_write_end(). For all the fields in png_info and
2506their data types, see png.h. For explanations of what the fields
2507contain, see the PNG specification.
2508
2509Some of the more important parts of the png_info are:
2510
2511 png_set_IHDR(png_ptr, info_ptr, width, height,
2512 bit_depth, color_type, interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2513 compression_type, filter_method)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2514 width - holds the width of the image
2515 in pixels (up to 2^31).
2516 height - holds the height of the image
2517 in pixels (up to 2^31).
2518 bit_depth - holds the bit depth of one of the
2519 image channels.
2520 (valid values are 1, 2, 4, 8, 16
2521 and depend also on the
2522 color_type. See also significant
2523 bits (sBIT) below).
2524 color_type - describes which color/alpha
2525 channels are present.
2526 PNG_COLOR_TYPE_GRAY
2527 (bit depths 1, 2, 4, 8, 16)
2528 PNG_COLOR_TYPE_GRAY_ALPHA
2529 (bit depths 8, 16)
2530 PNG_COLOR_TYPE_PALETTE
2531 (bit depths 1, 2, 4, 8)
2532 PNG_COLOR_TYPE_RGB
2533 (bit_depths 8, 16)
2534 PNG_COLOR_TYPE_RGB_ALPHA
2535 (bit_depths 8, 16)
2536
2537 PNG_COLOR_MASK_PALETTE
2538 PNG_COLOR_MASK_COLOR
2539 PNG_COLOR_MASK_ALPHA
2540
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2541 interlace_type - PNG_INTERLACE_NONE or
2542 PNG_INTERLACE_ADAM7
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2543 compression_type - (must be
2544 PNG_COMPRESSION_TYPE_DEFAULT)
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2545 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
2546 or, if you are writing a PNG to
2547 be embedded in a MNG datastream,
2548 can also be
2549 PNG_INTRAPIXEL_DIFFERENCING)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2550
2551 png_set_PLTE(png_ptr, info_ptr, palette,
2552 num_palette);
2553 palette - the palette for the file
2554 (array of png_color)
2555 num_palette - number of entries in the palette
2556
2557 png_set_gAMA(png_ptr, info_ptr, gamma);
2558 gamma - the gamma the image was created
2559 at (PNG_INFO_gAMA)
2560
2561 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2562 srgb_intent - the rendering intent
2563 (PNG_INFO_sRGB) The presence of
2564 the sRGB chunk means that the pixel
2565 data is in the sRGB color space.
2566 This chunk also implies specific
2567 values of gAMA and cHRM. Rendering
2568 intent is the CSS-1 property that
2569 has been defined by the International
2570 Color Consortium
2571 (http://www.color.org).
2572 It can be one of
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]2573 PNG_sRGB_INTENT_SATURATION,
2574 PNG_sRGB_INTENT_PERCEPTUAL,
2575 PNG_sRGB_INTENT_ABSOLUTE, or
2576 PNG_sRGB_INTENT_RELATIVE.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2577
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2578
2579 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2580 srgb_intent);
2581 srgb_intent - the rendering intent
2582 (PNG_INFO_sRGB) The presence of the
2583 sRGB chunk means that the pixel
2584 data is in the sRGB color space.
2585 This function also causes gAMA and
2586 cHRM chunks with the specific values
2587 that are consistent with sRGB to be
2588 written.
2589
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2590 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2591 profile, proflen);
2592 name - The profile name.
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2593 compression - The compression type; always
2594 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2595 You may give NULL to this argument to
2596 ignore it.
2597 profile - International Color Consortium color
2598 profile data. May contain NULs.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2599 proflen - length of profile data in bytes.
2600
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2601 png_set_sBIT(png_ptr, info_ptr, sig_bit);
2602 sig_bit - the number of significant bits for
2603 (PNG_INFO_sBIT) each of the gray, red,
2604 green, and blue channels, whichever are
2605 appropriate for the given color type
2606 (png_color_16)
2607
2608 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2609 trans_values);
2610 trans - array of transparent entries for
2611 palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]2612 trans_values - graylevel or color sample values of
2613 the single transparent color for
2614 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2615 num_trans - number of transparent entries
2616 (PNG_INFO_tRNS)
2617
2618 png_set_hIST(png_ptr, info_ptr, hist);
2619 (PNG_INFO_hIST)
2620 hist - histogram of palette (array of
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2621 png_uint_16)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2622
2623 png_set_tIME(png_ptr, info_ptr, mod_time);
2624 mod_time - time image was last modified
2625 (PNG_VALID_tIME)
2626
2627 png_set_bKGD(png_ptr, info_ptr, background);
2628 background - background color (PNG_VALID_bKGD)
2629
2630 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2631 text_ptr - array of png_text holding image
2632 comments
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2633 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2634 on "text" PNG_TEXT_COMPRESSION_NONE
2635 PNG_TEXT_COMPRESSION_zTXt
2636 PNG_ITXT_COMPRESSION_NONE
2637 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2638 text_ptr[i].key - keyword for comment. Must contain
2639 1-79 characters.
2640 text_ptr[i].text - text comments for current
2641 keyword. Can be NULL or empty.
2642 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2643 after decompression, 0 for iTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2644 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2645 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2646 text_ptr[i].lang - language of comment (NULL or
2647 empty for unknown).
2648 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
2649 or empty for unknown).
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2650 num_text - number of comments
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2651
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2652 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2653 num_spalettes);
2654 palette_ptr - array of png_sPLT_struct structures
2655 to be added to the list of palettes
2656 in the info structure.
2657 num_spalettes - number of palette structures to be
2658 added.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2659
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2660 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2661 unit_type);
2662 offset_x - positive offset from the left
2663 edge of the screen
2664 offset_y - positive offset from the top
2665 edge of the screen
2666 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2667
2668 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2669 unit_type);
2670 res_x - pixels/unit physical resolution
2671 in x direction
2672 res_y - pixels/unit physical resolution
2673 in y direction
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2674 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2675 PNG_RESOLUTION_METER
2676
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2677 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2678 unit - physical scale units (an integer)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2679 width - width of a pixel in physical scale units
2680 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2681 (width and height are doubles)
2682
2683 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2684 unit - physical scale units (an integer)
2685 width - width of a pixel in physical scale units
2686 height - height of a pixel in physical scale units
2687 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2688
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2689 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2690 num_unknowns)
2691 unknowns - array of png_unknown_chunk
2692 structures holding unknown chunks
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2693 unknowns[i].name - name of unknown chunk
2694 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2695 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2696 unknowns[i].location - position to write chunk in file
2697 0: do not write chunk
2698 PNG_HAVE_IHDR: before PLTE
2699 PNG_HAVE_PLTE: before IDAT
2700 PNG_AFTER_IDAT: after IDAT
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2701
2702The "location" member is set automatically according to
2703what part of the output file has already been written.
2704You can change its value after calling png_set_unknown_chunks()
2705as demonstrated in pngtest.c. Within each of the "locations",
2706the chunks are sequenced according to their position in the
2707structure (that is, the value of "i", which is the order in which
2708the chunk was either read from the input file or defined with
2709png_set_unknown_chunks).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2710
2711A quick word about text and num_text. text is an array of png_text
2712structures. num_text is the number of valid structures in the array.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2713Each png_text structure holds a language code, a keyword, a text value,
2714and a compression type.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2715
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2716The compression types have the same valid numbers as the compression
2717types of the image data. Currently, the only valid number is zero.
2718However, you can store text either compressed or uncompressed, unlike
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2719images, which always have to be compressed. So if you don't want the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2720text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2721Because tEXt and zTXt chunks don't have a language field, if you
2722specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
2723any language code or translated keyword will not be written out.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2724
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2725Until text gets around 1000 bytes, it is not worth compressing it.
2726After the text has been written out to the file, the compression type
2727is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2728so that it isn't written out again at the end (in case you are calling
2729png_write_end() with the same struct.
2730
2731The keywords that are given in the PNG Specification are:
2732
2733 Title Short (one line) title or
2734 caption for image
2735 Author Name of image's creator
2736 Description Description of image (possibly long)
2737 Copyright Copyright notice
2738 Creation Time Time of original image creation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2739 (usually RFC 1123 format, see below)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2740 Software Software used to create the image
2741 Disclaimer Legal disclaimer
2742 Warning Warning of nature of content
2743 Source Device used to create the image
2744 Comment Miscellaneous comment; conversion
2745 from other image format
2746
2747The keyword-text pairs work like this. Keywords should be short
2748simple descriptions of what the comment is about. Some typical
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2749keywords are found in the PNG specification, as is some recommendations
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2750on keywords. You can repeat keywords in a file. You can even write
2751some text before the image and some after. For example, you may want
2752to put a description of the image before the image, but leave the
2753disclaimer until after, so viewers working over modem connections
2754don't have to wait for the disclaimer to go over the modem before
2755they start seeing the image. Finally, keywords should be full
2756words, not abbreviations. Keywords and text are in the ISO 8859-1
2757(Latin-1) character set (a superset of regular ASCII) and can not
2758contain NUL characters, and should not contain control or other
2759unprintable characters. To make the comments widely readable, stick
2760with basic ASCII, and avoid machine specific character set extensions
2761like the IBM-PC character set. The keyword must be present, but
2762you can leave off the text string on non-compressed pairs.
2763Compressed pairs must have a text string, as only the text string
2764is compressed anyway, so the compression would be meaningless.
2765
2766PNG supports modification time via the png_time structure. Two
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2767conversion routines are provided, png_convert_from_time_t() for
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2768time_t and png_convert_from_struct_tm() for struct tm. The
2769time_t routine uses gmtime(). You don't have to use either of
2770these, but if you wish to fill in the png_time structure directly,
2771you should provide the time in universal time (GMT) if possible
2772instead of your local time. Note that the year number is the full
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2773year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2774that months start with 1.
2775
2776If you want to store the time of the original image creation, you should
2777use a plain tEXt chunk with the "Creation Time" keyword. This is
2778necessary because the "creation time" of a PNG image is somewhat vague,
2779depending on whether you mean the PNG file, the time the image was
2780created in a non-PNG format, a still photo from which the image was
2781scanned, or possibly the subject matter itself. In order to facilitate
2782machine-readable dates, it is recommended that the "Creation Time"
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2783tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2784although this isn't a requirement. Unlike the tIME chunk, the
2785"Creation Time" tEXt chunk is not expected to be automatically changed
2786by the software. To facilitate the use of RFC 1123 dates, a function
2787png_convert_to_rfc1123(png_timep) is provided to convert from PNG
2788time to an RFC 1123 format string.
2789
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2790.SS Writing unknown chunks
2791
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2792You can use the png_set_unknown_chunks function to queue up chunks
2793for writing. You give it a chunk name, raw data, and a size; that's
2794all there is to it. The chunks will be written by the next following
2795png_write_info_before_PLTE, png_write_info, or png_write_end function.
2796Any chunks previously read into the info structure's unknown-chunk
2797list will also be written out in a sequence that satisfies the PNG
2798specification's ordering rules.
2799
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2800.SS The high-level write interface
2801
2802At this point there are two ways to proceed; through the high-level
2803write interface, or through a sequence of low-level write operations.
2804You can use the high-level interface if your image data is present
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2805in the info structure. All defined output
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2806transformations are permitted, enabled by the following masks.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2807
2808 PNG_TRANSFORM_IDENTITY No transformation
2809 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2810 PNG_TRANSFORM_PACKSWAP Change order of packed
2811 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2812 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2813 PNG_TRANSFORM_SHIFT Normalize pixels to the
2814 sBIT depth
2815 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
2816 to BGRA
2817 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
2818 to AG
2819 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
2820 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2821 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
2822 PNG_TRANSFORM_STRIP_FILLER Strip out filler bytes.
2823
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2824If you have valid image data in the info structure (you can use
2825png_set_rows() to put image data in the info structure), simply do this:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2826
2827 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
2828
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2829where png_transforms is an integer containing the bitwise OR of some set of
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2830transformation flags. This call is equivalent to png_write_info(),
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2831followed the set of transformations indicated by the transform mask,
2832then png_write_image(), and finally png_write_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2833
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2834(The final parameter of this call is not yet used. Someday it might point
2835to transformation parameters required by some future output transform.)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2836
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]2837You must use png_transforms and not call any png_set_transform() functions
2838when you use png_write_png().
2839
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2840.SS The low-level write interface
2841
2842If you are going the low-level route instead, you are now ready to
2843write all the file information up to the actual image data. You do
2844this with a call to png_write_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2845
2846 png_write_info(png_ptr, info_ptr);
2847
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2848Note that there is one transformation you may need to do before
2849png_write_info(). In PNG files, the alpha channel in an image is the
2850level of opacity. If your data is supplied as a level of
2851transparency, you can invert the alpha channel before you write it, so
2852that 0 is fully transparent and 255 (in 8-bit or paletted images) or
285365535 (in 16-bit images) is fully opaque, with
2854
2855 png_set_invert_alpha(png_ptr);
2856
2857This must appear before png_write_info() instead of later with the
2858other transformations because in the case of paletted images the tRNS
2859chunk data has to be inverted before the tRNS chunk is written. If
2860your image is not a paletted image, the tRNS data (which in such cases
2861represents a single color to be rendered as transparent) won't need to
2862be changed, and you can safely do this transformation after your
2863png_write_info() call.
2864
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]2865If you need to write a private chunk that you want to appear before
2866the PLTE chunk when PLTE is present, you can write the PNG info in
2867two steps, and insert code to write your own chunk between them:
2868
2869 png_write_info_before_PLTE(png_ptr, info_ptr);
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2870 png_set_unknown_chunks(png_ptr, info_ptr, ...);
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]2871 png_write_info(png_ptr, info_ptr);
2872
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2873After you've written the file information, you can set up the library
2874to handle any special transformations of the image data. The various
2875ways to transform the data will be described in the order that they
2876should occur. This is important, as some of these change the color
2877type and/or bit depth of the data, and some others only work on
2878certain color types and bit depths. Even though each transformation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2879checks to see if it has data that it can do something with, you should
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2880make sure to only enable a transformation if it will be valid for the
2881data. For example, don't swap red and blue on grayscale data.
2882
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2883PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]2884the library to strip input data that has 4 or 8 bytes per pixel down
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2885to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
2886bytes per pixel).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2887
2888 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
2889
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2890where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2891PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
2892is stored XRGB or RGBX.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2893
2894PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2895they can, resulting in, for example, 8 pixels per byte for 1 bit files.
2896If the data is supplied at 1 pixel per byte, use this code, which will
2897correctly pack the pixels into a single byte:
2898
2899 png_set_packing(png_ptr);
2900
2901PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
2902data is of another bit depth, you can write an sBIT chunk into the
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2903file so that decoders can recover the original data if desired.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2904
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2905 /* Set the true bit depth of the image data */
2906 if (color_type & PNG_COLOR_MASK_COLOR)
2907 {
2908 sig_bit.red = true_bit_depth;
2909 sig_bit.green = true_bit_depth;
2910 sig_bit.blue = true_bit_depth;
2911 }
2912 else
2913 {
2914 sig_bit.gray = true_bit_depth;
2915 }
2916 if (color_type & PNG_COLOR_MASK_ALPHA)
2917 {
2918 sig_bit.alpha = true_bit_depth;
2919 }
2920
2921 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
2922
2923If the data is stored in the row buffer in a bit depth other than
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2924one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2925this will scale the values to appear to be the correct bit depth as
2926is required by PNG.
2927
2928 png_set_shift(png_ptr, &sig_bit);
2929
2930PNG files store 16 bit pixels in network byte order (big-endian,
2931ie. most significant bits first). This code would be used if they are
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2932supplied the other way (little-endian, i.e. least significant bits
2933first, the way PCs store them):
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2934
2935 if (bit_depth > 8)
2936 png_set_swap(png_ptr);
2937
2938If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2939need to change the order the pixels are packed into bytes, you can use:
2940
2941 if (bit_depth < 8)
2942 png_set_packswap(png_ptr);
2943
2944PNG files store 3 color pixels in red, green, blue order. This code
2945would be used if they are supplied as blue, green, red:
2946
2947 png_set_bgr(png_ptr);
2948
2949PNG files describe monochrome as black being zero and white being
2950one. This code would be used if the pixels are supplied with this reversed
2951(black being one and white being zero):
2952
2953 png_set_invert_mono(png_ptr);
2954
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2955Finally, you can write your own transformation function if none of
2956the existing ones meets your needs. This is done by setting a callback
2957with
2958
2959 png_set_write_user_transform_fn(png_ptr,
2960 write_transform_fn);
2961
2962You must supply the function
2963
2964 void write_transform_fn(png_ptr ptr, row_info_ptr
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2965 row_info, png_bytep data)
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2966
2967See pngtest.c for a working example. Your function will be called
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2968before any of the other transformations are processed.
2969
2970You can also set up a pointer to a user structure for use by your
2971callback function.
2972
2973 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
2974
2975The user_channels and user_depth parameters of this function are ignored
2976when writing; you can set them to zero as shown.
2977
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2978You can retrieve the pointer via the function png_get_user_transform_ptr().
2979For example:
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2980
2981 voidp write_user_transform_ptr =
2982 png_get_user_transform_ptr(png_ptr);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2983
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2984It is possible to have libpng flush any pending output, either manually,
2985or automatically after a certain number of lines have been written. To
2986flush the output stream a single time call:
2987
2988 png_write_flush(png_ptr);
2989
2990and to have libpng flush the output stream periodically after a certain
2991number of scanlines have been written, call:
2992
2993 png_set_flush(png_ptr, nrows);
2994
2995Note that the distance between rows is from the last time png_write_flush()
2996was called, or the first row of the image if it has never been called.
2997So if you write 50 lines, and then png_set_flush 25, it will flush the
2998output on the next scanline, and every 25 lines thereafter, unless
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2999png_write_flush() is called before 25 more lines have been written.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3000If nrows is too small (less than about 10 lines for a 640 pixel wide
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3001RGB image) the image compression may decrease noticeably (although this
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3002may be acceptable for real-time applications). Infrequent flushing will
3003only degrade the compression performance by a few percent over images
3004that do not use flushing.
3005
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3006.SS Writing the image data
3007
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3008That's it for the transformations. Now you can write the image data.
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3009The simplest way to do this is in one function call. If you have the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3010whole image in memory, you can just call png_write_image() and libpng
3011will write the image. You will need to pass in an array of pointers to
3012each row. This function automatically handles interlacing, so you don't
3013need to call png_set_interlace_handling() or call this function multiple
3014times, or any of that other stuff necessary with png_write_rows().
3015
3016 png_write_image(png_ptr, row_pointers);
3017
3018where row_pointers is:
3019
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3020 png_byte *row_pointers[height];
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3021
3022You can point to void or char or whatever you use for pixels.
3023
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3024If you don't want to write the whole image at once, you can
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3025use png_write_rows() instead. If the file is not interlaced,
3026this is simple:
3027
3028 png_write_rows(png_ptr, row_pointers,
3029 number_of_rows);
3030
3031row_pointers is the same as in the png_write_image() call.
3032
3033If you are just writing one row at a time, you can do this with
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3034a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3035
3036 png_bytep row_pointer = row;
3037
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3038 png_write_row(png_ptr, row_pointer);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3039
3040When the file is interlaced, things can get a good deal more
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3041complicated. The only currently (as of the PNG Specification
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3042version 1.2, dated July 1999) defined interlacing scheme for PNG files
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3043is the "Adam7" interlace scheme, that breaks down an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3044image into seven smaller images of varying size. libpng will build
3045these images for you, or you can do them yourself. If you want to
3046build them yourself, see the PNG specification for details of which
3047pixels to write when.
3048
3049If you don't want libpng to handle the interlacing details, just
3050use png_set_interlace_handling() and call png_write_rows() the
3051correct number of times to write all seven sub-images.
3052
3053If you want libpng to build the sub-images, call this before you start
3054writing any rows:
3055
3056 number_of_passes =
3057 png_set_interlace_handling(png_ptr);
3058
3059This will return the number of passes needed. Currently, this
3060is seven, but may change if another interlace type is added.
3061
3062Then write the complete image number_of_passes times.
3063
3064 png_write_rows(png_ptr, row_pointers,
3065 number_of_rows);
3066
3067As some of these rows are not used, and thus return immediately,
3068you may want to read about interlacing in the PNG specification,
3069and only update the rows that are actually used.
3070
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3071.SS Finishing a sequential write
3072
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3073After you are finished writing the image, you should finish writing
3074the file. If you are interested in writing comments or time, you should
3075pass an appropriately filled png_info pointer. If you are not interested,
3076you can pass NULL.
3077
3078 png_write_end(png_ptr, info_ptr);
3079
3080When you are done, you can free all memory used by libpng like this:
3081
3082 png_destroy_write_struct(&png_ptr, &info_ptr);
3083
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3084It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3085point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3086
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3087 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3088 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3089 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3090 more of
3091 PNG_FREE_PLTE, PNG_FREE_TRNS,
3092 PNG_FREE_HIST, PNG_FREE_ICCP,
3093 PNG_FREE_PCAL, PNG_FREE_ROWS,
3094 PNG_FREE_SCAL, PNG_FREE_SPLT,
3095 PNG_FREE_TEXT, PNG_FREE_UNKN,
3096 or simply PNG_FREE_ALL
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3097 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3098 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3099
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3100This function may be safely called when the relevant storage has
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3101already been freed, or has not yet been allocated, or was allocated
3102by the user and not by libpng, and will in those
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3103cases do nothing. The "seq" parameter is ignored if only one item
3104of the selected data type, such as PLTE, is allowed. If "seq" is not
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]3105-1, and multiple items are allowed for the data type identified in
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3106the mask, such as text or sPLT, only the n'th item in the structure
3107is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3108
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3109If you allocated data such as a palette that you passed
3110in to libpng with png_set_*, you must not free it until just before the call to
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3111png_destroy_write_struct().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3112
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3113The default behavior is only to free data that was allocated internally
3114by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3115or so that it will free data that was allocated by the user with png_malloc()
3116or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3117
3118 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3119 mask - which data elements are affected
3120 same choices as in png_free_data()
3121 freer - one of
3122 PNG_DESTROY_WILL_FREE_DATA
3123 PNG_SET_WILL_FREE_DATA
3124 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3125
3126For example, to transfer responsibility for some data from a read structure
3127to a write structure, you could use
3128
3129 png_data_freer(read_ptr, read_info_ptr,
3130 PNG_USER_WILL_FREE_DATA,
3131 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3132 png_data_freer(write_ptr, write_info_ptr,
3133 PNG_DESTROY_WILL_FREE_DATA,
3134 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3135
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3136thereby briefly reassigning responsibility for freeing to the user but
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3137immediately afterwards reassigning it once more to the write_destroy
3138function. Having done this, it would then be safe to destroy the read
3139structure and continue to use the PLTE, tRNS, and hIST data in the write
3140structure.
3141
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3142This function only affects data that has already been allocated.
3143You can call this function before calling after the png_set_*() functions
3144to control whether the user or png_destroy_*() is supposed to free the data.
3145When the user assumes responsibility for libpng-allocated data, the
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3146application must use
3147png_free() to free it, and when the user transfers responsibility to libpng
3148for data that the user has allocated, the user must have used png_malloc()
3149or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3150
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3151If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
3152separately, do not transfer responsibility for freeing text_ptr to libpng,
3153because when libpng fills a png_text structure it combines these members with
3154the key member, and png_free_data() will free only text_ptr.key. Similarly,
3155if you transfer responsibility for free'ing text_ptr from libpng to your
3156application, your application must not separately free those members.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3157For a more compact example of writing a PNG image, see the file example.c.
3158
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3159.SH V. Modifying/Customizing libpng:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3160
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]3161There are three issues here. The first is changing how libpng does
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3162standard things like memory allocation, input/output, and error handling.
3163The second deals with more complicated things like adding new chunks,
3164adding new transformations, and generally changing how libpng works.
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]3165Both of those are compile-time issues; that is, they are generally
3166determined at the time the code is written, and there is rarely a need
3167to provide the user with a means of changing them. The third is a
3168run-time issue: choosing between and/or tuning one or more alternate
3169versions of computationally intensive routines; specifically, optimized
3170assembly-language (and therefore compiler- and platform-dependent)
3171versions.
3172
3173Memory allocation, input/output, and error handling
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3174
3175All of the memory allocation, input/output, and error handling in libpng
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]3176goes through callbacks that are user-settable. The default routines are
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3177in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3178these functions, call the appropriate png_set_*_fn() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3179
Glenn Randers-Pehrsoncfbed9b2002-05-21 18:06:08 -0500[diff] [blame]3180Memory allocation is done through the functions png_malloc()
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3181and png_free(). These currently just call the standard C functions. If
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3182your pointers can't access more then 64K at a time, you will want to set
3183MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling
3184memory allocation on a platform will change between applications, these
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3185functions must be modified in the library at compile time. If you prefer
3186to use a different method of allocating and freeing data, you can use
Glenn Randers-Pehrsoncfbed9b2002-05-21 18:06:08 -0500[diff] [blame]3187png_create_read_struct_2() or png_create_write_struct_2() to register
3188your own functions as described above.
Glenn Randers-Pehrsoncfbed9b2002-05-21 18:06:08 -0500[diff] [blame]3189These functions also provide a void pointer that can be retrieved via
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3190
3191 mem_ptr=png_get_mem_ptr(png_ptr);
3192
3193Your replacement memory functions must have prototypes as follows:
3194
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3195 png_voidp malloc_fn(png_structp png_ptr,
Glenn Randers-Pehrsonae498dc2001-11-24 14:53:31 -0600[diff] [blame]3196 png_size_t size);
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3197 void free_fn(png_structp png_ptr, png_voidp ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3198
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3199Your malloc_fn() must return NULL in case of failure. The png_malloc()
3200function will normally call png_error() if it receives a NULL from the
3201system memory allocator or from your replacement malloc_fn().
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]3202
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3203Input/Output in libpng is done through png_read() and png_write(),
3204which currently just call fread() and fwrite(). The FILE * is stored in
3205png_struct and is initialized via png_init_io(). If you wish to change
3206the method of I/O, the library supplies callbacks that you can set
3207through the function png_set_read_fn() and png_set_write_fn() at run
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3208time, instead of calling the png_init_io() function. These functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3209also provide a void pointer that can be retrieved via the function
3210png_get_io_ptr(). For example:
3211
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]3212 png_set_read_fn(png_structp read_ptr,
3213 voidp read_io_ptr, png_rw_ptr read_data_fn)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3214
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]3215 png_set_write_fn(png_structp write_ptr,
3216 voidp write_io_ptr, png_rw_ptr write_data_fn,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3217 png_flush_ptr output_flush_fn);
3218
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]3219 voidp read_io_ptr = png_get_io_ptr(read_ptr);
3220 voidp write_io_ptr = png_get_io_ptr(write_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3221
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3222The replacement I/O functions must have prototypes as follows:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3223
3224 void user_read_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]3225 png_bytep data, png_size_t length);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3226 void user_write_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]3227 png_bytep data, png_size_t length);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3228 void user_flush_data(png_structp png_ptr);
3229
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3230The user_read_data() function is responsible for detecting and
3231handling end-of-data errors.
3232
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3233Supplying NULL for the read, write, or flush functions sets them back
3234to using the default C stream functions. It is an error to read from
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3235a write stream, and vice versa.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3236
3237Error handling in libpng is done through png_error() and png_warning().
3238Errors handled through png_error() are fatal, meaning that png_error()
3239should never return to its caller. Currently, this is handled via
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3240setjmp() and longjmp() (unless you have compiled libpng with
3241PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
3242but you could change this to do things like exit() if you should wish.
3243
3244On non-fatal errors, png_warning() is called
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3245to print a warning message, and then control returns to the calling code.
3246By default png_error() and png_warning() print a message on stderr via
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3247fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
3248(because you don't want the messages) or PNG_NO_STDIO defined (because
3249fprintf() isn't available). If you wish to change the behavior of the error
3250functions, you will need to set up your own message callbacks. These
3251functions are normally supplied at the time that the png_struct is created.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3252It is also possible to redirect errors and warnings to your own replacement
3253functions after png_create_*_struct() has been called by calling:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3254
3255 png_set_error_fn(png_structp png_ptr,
3256 png_voidp error_ptr, png_error_ptr error_fn,
3257 png_error_ptr warning_fn);
3258
3259 png_voidp error_ptr = png_get_error_ptr(png_ptr);
3260
3261If NULL is supplied for either error_fn or warning_fn, then the libpng
3262default function will be used, calling fprintf() and/or longjmp() if a
3263problem is encountered. The replacement error functions should have
3264parameters as follows:
3265
3266 void user_error_fn(png_structp png_ptr,
3267 png_const_charp error_msg);
3268 void user_warning_fn(png_structp png_ptr,
3269 png_const_charp warning_msg);
3270
3271The motivation behind using setjmp() and longjmp() is the C++ throw and
3272catch exception handling methods. This makes the code much easier to write,
3273as there is no need to check every return code of every function call.
3274However, there are some uncertainties about the status of local variables
3275after a longjmp, so the user may want to be careful about doing anything after
3276setjmp returns non-zero besides returning itself. Consult your compiler
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3277documentation for more details. For an alternative approach, you may wish
3278to use the "cexcept" facility (see http://cexcept.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3279
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3280.SS Custom chunks
3281
3282If you need to read or write custom chunks, you may need to get deeper
3283into the libpng code. The library now has mechanisms for storing
3284and writing chunks of unknown type; you can even declare callbacks
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]3285for custom chunks. However, this may not be good enough if the
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3286library code itself needs to know about interactions between your
3287chunk and existing `intrinsic' chunks.
3288
3289If you need to write a new intrinsic chunk, first read the PNG
3290specification. Acquire a first level of
3291understanding of how it works. Pay particular attention to the
3292sections that describe chunk names, and look at how other chunks were
3293designed, so you can do things similarly. Second, check out the
3294sections of libpng that read and write chunks. Try to find a chunk
3295that is similar to yours and use it as a template. More details can
3296be found in the comments inside the code. It is best to handle unknown
3297chunks in a generic method, via callback functions, instead of by
3298modifying libpng functions.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3299
3300If you wish to write your own transformation for the data, look through
3301the part of the code that does the transformations, and check out some of
3302the simpler ones to get an idea of how they work. Try to find a similar
3303transformation to the one you want to add and copy off of it. More details
3304can be found in the comments inside the code itself.
3305
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3306.SS Configuring for 16 bit platforms
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3307
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3308You will want to look into zconf.h to tell zlib (and thus libpng) that
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3309it cannot allocate more then 64K at a time. Even if you can, the memory
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3310won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3311
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3312.SS Configuring for DOS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3313
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3314For DOS users who only have access to the lower 640K, you will
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3315have to limit zlib's memory usage via a png_set_compression_mem_level()
3316call. See zlib.h or zconf.h in the zlib library for more information.
3317
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3318.SS Configuring for Medium Model
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3319
3320Libpng's support for medium model has been tested on most of the popular
3321compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
3322defined, and FAR gets defined to far in pngconf.h, and you should be
3323all set. Everything in the library (except for zlib's structure) is
3324expecting far data. You must use the typedefs with the p or pp on
3325the end for pointers (or at least look at them and be careful). Make
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3326note that the rows of data are defined as png_bytepp, which is an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3327unsigned char far * far *.
3328
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3329.SS Configuring for gui/windowing platforms:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3330
3331You will need to write new error and warning functions that use the GUI
3332interface, as described previously, and set them to be the error and
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3333warning functions at the time that png_create_*_struct() is called,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3334in order to have them available during the structure initialization.
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3335They can be changed later via png_set_error_fn(). On some compilers,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3336you may also have to change the memory allocators (png_malloc, etc.).
3337
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3338.SS Configuring for compiler xxx:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3339
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]3340All includes for libpng are in pngconf.h. If you need to add, change
3341or delete an include, this is the place to do it. The includes that
3342are not needed outside libpng are placed inside pngpriv.h, which is
3343only used by the routines inside libpng itself.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3344
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3345.SS Configuring zlib:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3346
3347There are special functions to configure the compression. Perhaps the
3348most useful one changes the compression level, which currently uses
3349input compression values in the range 0 - 9. The library normally
3350uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
3351have shown that for a large majority of images, compression values in
3352the range 3-6 compress nearly as well as higher levels, and do so much
3353faster. For online applications it may be desirable to have maximum speed
3354(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
3355specify no compression (Z_NO_COMPRESSION = 0), but this would create
3356files larger than just storing the raw bitmap. You can specify the
3357compression level by calling:
3358
3359 png_set_compression_level(png_ptr, level);
3360
3361Another useful one is to reduce the memory level used by the library.
3362The memory level defaults to 8, but it can be lowered if you are
3363short on memory (running DOS, for example, where you only have 640K).
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3364Note that the memory level does have an effect on compression; among
3365other things, lower levels will result in sections of incompressible
3366data being emitted in smaller stored blocks, with a correspondingly
3367larger relative overhead of up to 15% in the worst case.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3368
3369 png_set_compression_mem_level(png_ptr, level);
3370
3371The other functions are for configuring zlib. They are not recommended
3372for normal use and may result in writing an invalid PNG file. See
3373zlib.h for more information on what these mean.
3374
3375 png_set_compression_strategy(png_ptr,
3376 strategy);
3377 png_set_compression_window_bits(png_ptr,
3378 window_bits);
3379 png_set_compression_method(png_ptr, method);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3380 png_set_compression_buffer_size(png_ptr, size);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3381
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3382.SS Controlling row filtering
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3383
3384If you want to control whether libpng uses filtering or not, which
3385filters are used, and how it goes about picking row filters, you
3386can call one of these functions. The selection and configuration
3387of row filters can have a significant impact on the size and
3388encoding speed and a somewhat lesser impact on the decoding speed
3389of an image. Filtering is enabled by default for RGB and grayscale
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3390images (with and without alpha), but not for paletted images nor
3391for any images with bit depths less than 8 bits/pixel.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3392
3393The 'method' parameter sets the main filtering method, which is
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3394currently only '0' in the PNG 1.2 specification. The 'filters'
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3395parameter sets which filter(s), if any, should be used for each
3396scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
3397to turn filtering on and off, respectively.
3398
3399Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
3400PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3401ORed together with '|' to specify one or more filters to use.
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3402These filters are described in more detail in the PNG specification.
3403If you intend to change the filter type during the course of writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3404the image, you should start with flags set for all of the filters
3405you intend to use so that libpng can initialize its internal
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3406structures appropriately for all of the filter types. (Note that this
3407means the first row must always be adaptively filtered, because libpng
3408currently does not allocate the filter buffers until png_write_row()
3409is called for the first time.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3410
3411 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3412 PNG_FILTER_UP | PNG_FILTER_AVE |
3413 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3414
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3415 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3416 filters);
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3417 The second parameter can also be
3418 PNG_INTRAPIXEL_DIFFERENCING if you are
3419 writing a PNG to be embedded in a MNG
3420 datastream. This parameter must be the
3421 same as the value of filter_method used
3422 in png_set_IHDR().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3423
3424It is also possible to influence how libpng chooses from among the
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3425available filters. This is done in one or both of two ways - by
3426telling it how important it is to keep the same filter for successive
3427rows, and by telling it the relative computational costs of the filters.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3428
3429 double weights[3] = {1.5, 1.3, 1.1},
3430 costs[PNG_FILTER_VALUE_LAST] =
3431 {1.0, 1.3, 1.3, 1.5, 1.7};
3432
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3433 png_set_filter_heuristics(png_ptr,
3434 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3435 weights, costs);
3436
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3437The weights are multiplying factors that indicate to libpng that the
3438row filter should be the same for successive rows unless another row filter
3439is that many times better than the previous filter. In the above example,
3440if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3441"sum of absolute differences" 1.5 x 1.3 times higher than other filters
3442and still be chosen, while the NONE filter could have a sum 1.1 times
3443higher than other filters and still be chosen. Unspecified weights are
3444taken to be 1.0, and the specified weights should probably be declining
3445like those above in order to emphasize recent filters over older filters.
3446
3447The filter costs specify for each filter type a relative decoding cost
3448to be considered when selecting row filters. This means that filters
3449with higher costs are less likely to be chosen over filters with lower
3450costs, unless their "sum of absolute differences" is that much smaller.
3451The costs do not necessarily reflect the exact computational speeds of
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3452the various filters, since this would unduly influence the final image
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3453size.
3454
3455Note that the numbers above were invented purely for this example and
3456are given only to help explain the function usage. Little testing has
3457been done to find optimum values for either the costs or the weights.
3458
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3459.SS Removing unwanted object code
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3460
3461There are a bunch of #define's in pngconf.h that control what parts of
3462libpng are compiled. All the defines end in _SUPPORTED. If you are
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3463never going to use a capability, you can change the #define to #undef
3464before recompiling libpng and save yourself code and data space, or
3465you can turn off individual capabilities with defines that begin with
3466PNG_NO_.
3467
3468You can also turn all of the transforms and ancillary chunk capabilities
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3469off en masse with compiler directives that define
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3470PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
3471or all four,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3472along with directives to turn on any of the capabilities that you do
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3473want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3474the extra transformations but still leave the library fully capable of reading
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3475and writing PNG files with all known public chunks
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3476Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3477produces a library that is incapable of reading or writing ancillary chunks.
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3478If you are not using the progressive reading capability, you can
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3479turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3480this with the INTERLACING capability, which you'll still have).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3481
3482All the reading and writing specific code are in separate files, so the
3483linker should only grab the files it needs. However, if you want to
3484make sure, or if you are building a stand alone library, all the
3485reading files start with pngr and all the writing files start with
3486pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
3487are used for both reading and writing, and always need to be included.
3488The progressive reader is in pngpread.c
3489
3490If you are creating or distributing a dynamically linked library (a .so
3491or DLL file), you should not remove or disable any parts of the library,
3492as this will cause applications linked with different versions of the
3493library to fail if they call functions not available in your library.
3494The size of the library itself should not be an issue, because only
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3495those sections that are actually used will be loaded into memory.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3496
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3497.SS Requesting debug printout
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3498
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3499The macro definition PNG_DEBUG can be used to request debugging
3500printout. Set it to an integer value in the range 0 to 3. Higher
3501numbers result in increasing amounts of debugging information. The
3502information is printed to the "stderr" file, unless another file
3503name is specified in the PNG_DEBUG_FILE macro definition.
3504
3505When PNG_DEBUG > 0, the following functions (macros) become available:
3506
3507 png_debug(level, message)
3508 png_debug1(level, message, p1)
3509 png_debug2(level, message, p1, p2)
3510
3511in which "level" is compared to PNG_DEBUG to decide whether to print
3512the message, "message" is the formatted string to be printed,
3513and p1 and p2 are parameters that are to be embedded in the string
3514according to printf-style formatting directives. For example,
3515
3516 png_debug1(2, "foo=%d\n", foo);
3517
3518is expanded to
3519
3520 if(PNG_DEBUG > 2)
3521 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
3522
3523When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
3524can still use PNG_DEBUG to control your own debugging:
3525
3526 #ifdef PNG_DEBUG
3527 fprintf(stderr, ...
3528 #endif
3529
3530When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
3531having level = 0 will be printed. There aren't any such statements in
3532this version of libpng, but if you insert some they will be printed.
3533
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3534.SH VI. Runtime optimization
3535
3536A new feature in libpng 1.2.0 is the ability to dynamically switch between
3537standard and optimized versions of some routines. Currently these are
3538limited to three computationally intensive tasks when reading PNG files:
3539decoding row filters, expanding interlacing, and combining interlaced or
3540transparent row data with previous row data. Currently the optimized
3541versions are available only for x86 (Intel, AMD, etc.) platforms with
3542MMX support, though this may change in future versions. (For example,
3543the non-MMX assembler optimizations for zlib might become similarly
3544runtime-selectable in future releases, in which case libpng could be
3545extended to support them. Alternatively, the compile-time choice of
3546floating-point versus integer routines for gamma correction might become
3547runtime-selectable.)
3548
3549Because such optimizations tend to be very platform- and compiler-dependent,
3550both in how they are written and in how they perform, the new runtime code
3551in libpng has been written to allow programs to query, enable, and disable
3552either specific optimizations or all such optimizations. For example, to
3553enable all possible optimizations (bearing in mind that some "optimizations"
3554may actually run more slowly in rare cases):
3555
3556 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3557 png_uint_32 mask, flags;
3558
3559 flags = png_get_asm_flags(png_ptr);
3560 mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
3561 png_set_asm_flags(png_ptr, flags | mask);
3562 #endif
3563
3564To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
3565by itself when calling png_get_asm_flagmask(); similarly for optimizing
3566only writing. To disable all optimizations:
3567
3568 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3569 flags = png_get_asm_flags(png_ptr);
3570 mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
3571 png_set_asm_flags(png_ptr, flags & ~mask);
3572 #endif
3573
3574To enable or disable only MMX-related features, use png_get_mmx_flagmask()
3575in place of png_get_asm_flagmask(). The mmx version takes one additional
3576parameter:
3577
3578 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3579 int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
3580 int compilerID;
3581
3582 mask = png_get_mmx_flagmask(selection, &compilerID);
3583 #endif
3584
3585On return, compilerID will indicate which version of the MMX assembler
3586optimizations was compiled. Currently two flavors exist: Microsoft
3587Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
3588On non-x86 platforms or on systems compiled without MMX optimizations, a
3589value of -1 is used.
3590
3591Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
3592all valid, settable optimization bits for the version of the library that's
3593currently in use. In the case of shared (dynamically linked) libraries,
3594this may include optimizations that did not exist at the time the code was
3595written and compiled. It is also possible, of course, to enable only known,
3596specific optimizations; for example:
3597
3598 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3599 flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
3600 | PNG_ASM_FLAG_MMX_READ_INTERLACE \
3601 | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
3602 | PNG_ASM_FLAG_MMX_READ_FILTER_UP \
3603 | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
3604 | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
3605 png_set_asm_flags(png_ptr, flags);
3606 #endif
3607
3608This method would enable only the MMX read-optimizations available at the
3609time of libpng 1.2.0's release, regardless of whether a later version of
3610the DLL were actually being used. (Also note that these functions did not
3611exist in versions older than 1.2.0, so any attempt to run a dynamically
3612linked app on such an older version would fail.)
3613
3614To determine whether the processor supports MMX instructions at all, use
3615the png_mmx_support() function:
3616
3617 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3618 mmxsupport = png_mmx_support();
3619 #endif
3620
3621It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
3622is compiled but MMX is not supported by the processor, or 1 if MMX support
3623is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
3624and png_get_asm_flagmask() all may be called without allocating and ini-
3625tializing any PNG structures (for example, as part of a usage screen or
3626"about" box).
3627
3628The following code can be used to prevent an application from using the
3629thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
3630defined:
3631
Glenn Randers-Pehrson17218292006-04-20 07:20:46 -0500[diff] [blame]3632#if defined(PNG_USE_PNGGCCRD) && defined(PNG_MMX_CODE_SUPPORTED) \
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3633 && defined(PNG_THREAD_UNSAFE_OK)
3634 /* Disable thread-unsafe features of pnggccrd */
Glenn Randers-Pehrson86dc9812006-05-10 07:27:44 -0500[diff] [blame]3635 if (png_access_version_number() >= 10200)
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3636 {
3637 png_uint_32 mmx_disable_mask = 0;
3638 png_uint_32 asm_flags;
3639
3640 mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
3641 | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
3642 | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
3643 | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
3644 asm_flags = png_get_asm_flags(png_ptr);
3645 png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
3646 }
3647#endif
3648
3649For more extensive examples of runtime querying, enabling and disabling
3650of optimized features, see contrib/gregbook/readpng2.c in the libpng
3651source-code distribution.
3652
3653.SH VII. MNG support
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]3654
3655The MNG specification (available at http://www.libpng.org/pub/mng) allows
3656certain extensions to PNG for PNG images that are embedded in MNG datastreams.
3657Libpng can support some of these extensions. To enable them, use the
3658png_permit_mng_features() function:
3659
3660 feature_set = png_permit_mng_features(png_ptr, mask)
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3661 mask is a png_uint_32 containing the bitwise OR of the
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]3662 features you want to enable. These include
3663 PNG_FLAG_MNG_EMPTY_PLTE
3664 PNG_FLAG_MNG_FILTER_64
3665 PNG_ALL_MNG_FEATURES
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3666 feature_set is a png_uint_32 that is the bitwise AND of
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]3667 your mask with the set of MNG features that is
3668 supported by the version of libpng that you are using.
3669
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3670It is an error to use this function when reading or writing a standalone
3671PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
Glenn Randers-Pehrsonf05f8032000-12-23 14:27:39 -0600[diff] [blame]3672in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
3673and the MHDR and MEND chunks. Libpng does not provide support for these
3674or any other MNG chunks; your application must provide its own support for
3675them. You may wish to consider using libmng (available at
3676http://www.libmng.com) instead.
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3677
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3678.SH VIII. Changes to Libpng from version 0.88
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3679
3680It should be noted that versions of libpng later than 0.96 are not
3681distributed by the original libpng author, Guy Schalnat, nor by
3682Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
3683distributed versions 0.89 through 0.96, but rather by another member
3684of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
3685still alive and well, but they have moved on to other things.
3686
3687The old libpng functions png_read_init(), png_write_init(),
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]3688png_info_init(), png_read_destroy(), and png_write_destroy() have been
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]3689moved to PNG_INTERNAL in version 0.95 to discourage their use. These
3690functions will be removed from libpng version 2.0.0.
3691
3692The preferred method of creating and initializing the libpng structures is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3693via the png_create_read_struct(), png_create_write_struct(), and
3694png_create_info_struct() because they isolate the size of the structures
3695from the application, allow version error checking, and also allow the
3696use of custom error handling routines during the initialization, which
3697the old functions do not. The functions png_read_destroy() and
3698png_write_destroy() do not actually free the memory that libpng
3699allocated for these structs, but just reset the data structures, so they
3700can be used instead of png_destroy_read_struct() and
3701png_destroy_write_struct() if you feel there is too much system overhead
3702allocating and freeing the png_struct for each image read.
3703
3704Setting the error callbacks via png_set_message_fn() before
3705png_read_init() as was suggested in libpng-0.88 is no longer supported
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3706because this caused applications that do not use custom error functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3707to fail if the png_ptr was not initialized to zero. It is still possible
3708to set the error callbacks AFTER png_read_init(), or to change them with
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]3709png_set_error_fn(), which is essentially the same function, but with a new
3710name to force compilation errors with applications that try to use the old
3711method.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3712
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3713Starting with version 1.0.7, you can find out which version of the library
3714you are using at run-time:
3715
3716 png_uint_32 libpng_vn = png_access_version_number();
3717
3718The number libpng_vn is constructed from the major version, minor
3719version with leading zero, and release number with leading zero,
3720(e.g., libpng_vn for version 1.0.7 is 10007).
3721
3722You can also check which version of png.h you used when compiling your
3723application:
3724
3725 png_uint_32 application_vn = PNG_LIBPNG_VER;
3726
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3727.SH IX. Y2K Compliance in libpng
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3728
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]3729August 14, 2008
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3730
3731Since the PNG Development group is an ad-hoc body, we can't make
3732an official declaration.
3733
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3734This is your unofficial assurance that libpng from version 0.71 and
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]3735upward through 1.4.0beta30 are Y2K compliant. It is my belief that earlier
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3736versions were also Y2K compliant.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3737
3738Libpng only has three year fields. One is a 2-byte unsigned integer that
3739will hold years up to 65535. The other two hold the date in text
3740format, and will hold years up to 9999.
3741
3742The integer is
3743 "png_uint_16 year" in png_time_struct.
3744
3745The strings are
3746 "png_charp time_buffer" in png_struct and
3747 "near_time_buffer", which is a local character string in png.c.
3748
3749There are seven time-related functions:
3750
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3751 png_convert_to_rfc_1123() in png.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3752 (formerly png_convert_to_rfc_1152() in error)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3753 png_convert_from_struct_tm() in pngwrite.c, called
3754 in pngwrite.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3755 png_convert_from_time_t() in pngwrite.c
3756 png_get_tIME() in pngget.c
3757 png_handle_tIME() in pngrutil.c, called in pngread.c
3758 png_set_tIME() in pngset.c
3759 png_write_tIME() in pngwutil.c, called in pngwrite.c
3760
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3761All appear to handle dates properly in a Y2K environment. The
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3762png_convert_from_time_t() function calls gmtime() to convert from system
3763clock time, which returns (year - 1900), which we properly convert to
3764the full 4-digit year. There is a possibility that applications using
3765libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3766function, or that they are incorrectly passing only a 2-digit year
3767instead of "year - 1900" into the png_convert_from_struct_tm() function,
3768but this is not under our control. The libpng documentation has always
3769stated that it works with 4-digit years, and the APIs have been
3770documented as such.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3771
3772The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
3773integer to hold the year, and can hold years as large as 65535.
3774
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3775zlib, upon which libpng depends, is also Y2K compliant. It contains
3776no date-related code.
3777
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3778
3779 Glenn Randers-Pehrson
3780 libpng maintainer
3781 PNG Development Group
3782
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3783.SH NOTE
3784
3785Note about libpng version numbers:
3786
3787Due to various miscommunications, unforeseen code incompatibilities
3788and occasional factors outside the authors' control, version numbering
3789on the library has not always been consistent and straightforward.
3790The following table summarizes matters since version 0.89c, which was
3791the first widely used release:
3792
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3793 source png.h png.h shared-lib
3794 version string int version
3795 ------- ------ ----- ----------
3796 0.89c ("beta 3") 0.89 89 1.0.89
3797 0.90 ("beta 4") 0.90 90 0.90
3798 0.95 ("beta 5") 0.95 95 0.95
3799 0.96 ("beta 6") 0.96 96 0.96
3800 0.97b ("beta 7") 1.00.97 97 1.0.1
3801 0.97c 0.97 97 2.0.97
3802 0.98 0.98 98 2.0.98
3803 0.99 0.99 98 2.0.99
3804 0.99a-m 0.99 99 2.0.99
3805 1.00 1.00 100 2.1.0
3806 1.0.0 1.0.0 100 2.1.0
3807 1.0.0 (from here on, the 100 2.1.0
3808 1.0.1 png.h string is 10001 2.1.0
3809 1.0.1a-e identical to the 10002 from here on, the
3810 1.0.2 source version) 10002 shared library is 2.V
3811 1.0.2a-b 10003 where V is the source
3812 1.0.1 10001 code version except as
3813 1.0.1a-e 10002 2.1.0.1a-e noted.
3814 1.0.2 10002 2.1.0.2
3815 1.0.2a-b 10003 2.1.0.2a-b
3816 1.0.3 10003 2.1.0.3
3817 1.0.3a-d 10004 2.1.0.3a-d
3818 1.0.4 10004 2.1.0.4
3819 1.0.4a-f 10005 2.1.0.4a-f
3820 1.0.5 (+ 2 patches) 10005 2.1.0.5
3821 1.0.5a-d 10006 2.1.0.5a-d
3822 1.0.5e-r 10100 2.1.0.5e-r
3823 1.0.5s-v 10006 2.1.0.5s-v
3824 1.0.6 (+ 3 patches) 10006 2.1.0.6
3825 1.0.6d-g 10007 2.1.0.6d-g
3826 1.0.6h 10007 10.6h
3827 1.0.6i 10007 10.6i
3828 1.0.6j 10007 2.1.0.6j
3829 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14
3830 1.0.7beta15-18 1 10007 2.1.0.7beta15-18
3831 1.0.7rc1-2 1 10007 2.1.0.7rc1-2
3832 1.0.7 1 10007 2.1.0.7
3833 1.0.8beta1-4 1 10008 2.1.0.8beta1-4
3834 1.0.8rc1 1 10008 2.1.0.8rc1
3835 1.0.8 1 10008 2.1.0.8
3836 1.0.9beta1-6 1 10009 2.1.0.9beta1-6
3837 1.0.9rc1 1 10009 2.1.0.9rc1
3838 1.0.9beta7-10 1 10009 2.1.0.9beta7-10
3839 1.0.9rc2 1 10009 2.1.0.9rc2
3840 1.0.9 1 10009 2.1.0.9
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]3841 1.0.10beta1 1 10010 2.1.0.10beta1
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3842 1.0.10rc1 1 10010 2.1.0.10rc1
Glenn Randers-Pehrson13cfbac2001-03-30 06:42:28 -0600[diff] [blame]3843 1.0.10 1 10010 2.1.0.10
Glenn Randers-Pehrsone1eff582001-04-14 20:15:41 -0500[diff] [blame]3844 1.0.11beta1-3 1 10011 2.1.0.11beta1-3
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]3845 1.0.11rc1 1 10011 2.1.0.11rc1
Glenn Randers-Pehrson32835392001-04-27 08:29:32 -0500[diff] [blame]3846 1.0.11 1 10011 2.1.0.11
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]3847 1.0.12beta1-2 2 10012 2.1.0.12beta1-2
3848 1.0.12rc1 2 10012 2.1.0.12rc1
3849 1.0.12 2 10012 2.1.0.12
3850 1.1.0a-f - 10100 2.1.1.0a-f abandoned
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]3851 1.2.0beta1-2 2 10200 2.1.2.0beta1-2
Glenn Randers-Pehrson5a0be342001-10-18 20:55:13 -0500[diff] [blame]3852 1.2.0beta3-5 3 10200 3.1.2.0beta3-5
3853 1.2.0rc1 3 10200 3.1.2.0rc1
3854 1.2.0 3 10200 3.1.2.0
Glenn Randers-Pehrson5cded0b2001-11-07 07:10:08 -0600[diff] [blame]3855 1.2.1beta-4 3 10201 3.1.2.1beta1-4
Glenn Randers-Pehrsondb3b88d2001-12-04 06:30:43 -0600[diff] [blame]3856 1.2.1rc1-2 3 10201 3.1.2.1rc1-2
3857 1.2.1 3 10201 3.1.2.1
Glenn Randers-Pehrson25228ab2002-03-31 07:33:55 -0600[diff] [blame]3858 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6
Glenn Randers-Pehrsonfcbd7872002-04-07 16:35:38 -0500[diff] [blame]3859 1.0.13beta1 10 10013 10.so.0.1.0.13beta1
3860 1.0.13rc1 10 10013 10.so.0.1.0.13rc1
3861 1.2.2rc1 12 10202 12.so.0.1.2.2rc1
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3862 1.0.13 10 10013 10.so.0.1.0.13
3863 1.2.2 12 10202 12.so.0.1.2.2
Glenn Randers-Pehrson22f28962002-05-13 18:17:09 -0500[diff] [blame]3864 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6
3865 1.2.3 12 10203 12.so.0.1.2.3
Glenn Randers-Pehrsond020e9d2002-06-28 09:34:00 -0500[diff] [blame]3866 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3
Glenn Randers-Pehrson2ae022d2002-07-01 22:23:46 -0500[diff] [blame]3867 1.2.4rc1 13 10204 12.so.0.1.2.4rc1
Glenn Randers-Pehrson484a8a12002-07-07 19:15:20 -0500[diff] [blame]3868 1.0.14 10 10014 10.so.0.1.0.14
3869 1.2.4 13 10204 12.so.0.1.2.4
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]3870 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
3871 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3872 1.0.15 10 10015 10.so.0.1.0.15
3873 1.2.5 13 10205 12.so.0.1.2.5
3874 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
Glenn Randers-Pehrson37f116a2004-08-15 07:15:39 -0500[diff] [blame]3875 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
3876 1.0.16 10 10016 10.so.0.1.0.16
3877 1.2.6 13 10206 12.so.0.1.2.6
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3878 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]3879 1.0.17rc1 10 10017 12.so.0.1.0.17rc1
3880 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
Glenn Randers-Pehrson250dfe12004-09-11 21:19:54 -0500[diff] [blame]3881 1.0.17 10 10017 12.so.0.1.0.17
3882 1.2.7 13 10207 12.so.0.1.2.7
Glenn Randers-Pehrson40936072004-11-20 11:18:40 -0600[diff] [blame]3883 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
Glenn Randers-Pehrson584b96e2004-11-29 15:08:00 -0600[diff] [blame]3884 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5
3885 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
Glenn Randers-Pehrson917648e2004-12-02 18:14:51 -0600[diff] [blame]3886 1.0.18 10 10018 12.so.0.1.0.18
3887 1.2.8 13 10208 12.so.0.1.2.8
Glenn Randers-Pehrsone6474622006-03-04 16:50:47 -0600[diff] [blame]3888 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
Glenn Randers-Pehrson4deeb792006-03-22 16:21:59 -0600[diff] [blame]3889 1.2.9beta4-11 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrson3a512032006-03-31 05:29:33 -0600[diff] [blame]3890 1.2.9rc1 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsona7d0c942006-04-14 06:22:52 -0500[diff] [blame]3891 1.2.9 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]3892 1.2.10beta1-7 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson17218292006-04-20 07:20:46 -0500[diff] [blame]3893 1.2.10rc1-2 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson86dc9812006-05-10 07:27:44 -0500[diff] [blame]3894 1.2.10 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]3895 1.4.0beta1-6 14 10400 14.so.0.0[.0]
3896 1.2.11beta1-4 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson3424ee72006-07-12 13:33:47 -0500[diff] [blame]3897 1.4.0beta7-8 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrson701dbaa2006-11-17 09:36:54 -0600[diff] [blame]3898 1.2.11 13 10211 12.so.0.11[.0]
3899 1.2.12 13 10212 12.so.0.12[.0]
3900 1.4.0beta9-14 14 10400 14.so.0.0[.0]
3901 1.2.13 13 10213 12.so.0.13[.0]
Glenn Randers-Pehrsone0784c72008-08-09 07:11:44 -0500[diff] [blame]3902 1.4.0beta15-29 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3903
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3904Henceforth the source version will match the shared-library minor
3905and patch numbers; the shared-library major version number will be
3906used for changes in backward compatibility, as it is intended. The
3907PNG_PNGLIB_VER macro, which is not used within libpng but is available
3908for applications, is an unsigned integer of the form xyyzz corresponding
3909to the source version x.y.z (leading zeros in y and z). Beta versions
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]3910were given the previous public release number plus a letter, until
3911version 1.0.6j; from then on they were given the upcoming public
3912release number plus "betaNN" or "rcN".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3913
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3914.SH "SEE ALSO"
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3915libpngpf(3), png(5)
3916.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3917.IR libpng :
3918.IP
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]3919http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]3920http://www.libpng.org/pub/png
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3921
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3922.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3923.IR zlib :
3924.IP
3925(generally) at the same location as
3926.I libpng
3927or at
3928.br
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]3929ftp://ftp.info-zip.org/pub/infozip/zlib
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3930
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3931.LP
3932.IR PNG specification: RFC 2083
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3933.IP
3934(generally) at the same location as
3935.I libpng
3936or at
3937.br
3938ftp://ds.internic.net/rfc/rfc2083.txt
3939.br
3940or (as a W3C Recommendation) at
3941.br
3942http://www.w3.org/TR/REC-png.html
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3943
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3944.LP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3945In the case of any inconsistency between the PNG specification
3946and this library, the specification takes precedence.
3947
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3948.SH AUTHORS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3949This man page: Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]3950<glennrp at users.sourceforge.net>
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3951
3952The contributing authors would like to thank all those who helped
3953with testing, bug fixes, and patience. This wouldn't have been
3954possible without all of you.
3955
3956Thanks to Frank J. T. Wojcik for helping with the documentation.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3957
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]3958Libpng version 1.4.0beta30 - August 14, 2008:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3959Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]3960Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3961
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3962Supported by the PNG development group
3963.br
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]3964png-mng-implement at lists.sf.net
3965(subscription required; visit
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]3966png-mng-implement at lists.sourceforge.net (subscription required; visit
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]3967https://lists.sourceforge.net/lists/listinfo/png-mng-implement
3968to subscribe).
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3969
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3970.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3971
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]3972(This copy of the libpng notices is provided for your convenience. In case of
3973any discrepancy between this copy and the notices in the file png.h that is
3974included in the libpng distribution, the latter shall prevail.)
3975
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3976If you modify libpng you may insert additional notices immediately following
3977this sentence.
3978
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]3979libpng versions 1.2.6, August 15, 2004, through 1.4.0beta30, August 14, 2008, are
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame]3980Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3981distributed according to the same disclaimer and license as libpng-1.2.5
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]3982with the following individual added to the list of Contributing Authors
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3983
3984 Cosmin Truta
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3985
3986libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are
Glenn Randers-Pehrsonc6de22d2002-02-23 18:55:25 -0600[diff] [blame]3987Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson32fc5ce2000-07-24 06:34:14 -0500[diff] [blame]3988distributed according to the same disclaimer and license as libpng-1.0.6
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3989with the following individuals added to the list of Contributing Authors
3990
3991 Simon-Pierre Cadieux
3992 Eric S. Raymond
3993 Gilles Vollant
3994
3995and with the following additions to the disclaimer:
3996
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3997 There is no warranty against interference with your
3998 enjoyment of the library or against infringement.
3999 There is no warranty that our efforts or the library
4000 will fulfill any of your particular purposes or needs.
4001 This library is provided with all faults, and the entire
4002 risk of satisfactory quality, performance, accuracy, and
4003 effort is with the user.
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4004
4005libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
4006Copyright (c) 1998, 1999 Glenn Randers-Pehrson
4007Distributed according to the same disclaimer and license as libpng-0.96,
4008with the following individuals added to the list of Contributing Authors:
4009
4010 Tom Lane
4011 Glenn Randers-Pehrson
4012 Willem van Schaik
4013
4014libpng versions 0.89, June 1996, through 0.96, May 1997, are
Glenn Randers-Pehrson54a066a1999-09-19 06:04:18 -0500[diff] [blame]4015Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4016Distributed according to the same disclaimer and license as libpng-0.88,
4017with the following individuals added to the list of Contributing Authors:
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]4018
4019 John Bowler
4020 Kevin Bracey
4021 Sam Bushell
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]4022 Magnus Holmgren
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]4023 Greg Roelofs
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4024 Tom Tanner
4025
4026libpng versions 0.5, May 1995, through 0.88, January 1996, are
4027Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
4028
4029For the purposes of this copyright and license, "Contributing Authors"
4030is defined as the following set of individuals:
4031
4032 Andreas Dilger
4033 Dave Martindale
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]4034 Guy Eric Schalnat
4035 Paul Schmidt
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]4036 Tim Wegner
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]4037
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4038The PNG Reference Library is supplied "AS IS". The Contributing Authors
4039and Group 42, Inc. disclaim all warranties, expressed or implied,
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4040including, without limitation, the warranties of merchantability and of
4041fitness for any purpose. The Contributing Authors and Group 42, Inc.
4042assume no liability for direct, indirect, incidental, special, exemplary,
4043or consequential damages, which may result from the use of the PNG
4044Reference Library, even if advised of the possibility of such damage.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4045
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4046Permission is hereby granted to use, copy, modify, and distribute this
4047source code, or portions hereof, for any purpose, without fee, subject
4048to the following restrictions:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4049
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]40501. The origin of this source code must not be misrepresented.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4051
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]40522. Altered versions must be plainly marked as such and
4053 must not be misrepresented as being the original source.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4054
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]40553. This Copyright notice may not be removed or altered from
4056 any source or altered source distribution.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4057
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4058The Contributing Authors and Group 42, Inc. specifically permit, without
4059fee, and encourage the use of this source code as a component to
4060supporting the PNG file format in commercial products. If you use this
4061source code in a product, acknowledgment is not required but would be
4062appreciated.
4063
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4064
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]4065A "png_get_copyright" function is available, for convenient use in "about"
4066boxes and the like:
4067
4068 printf("%s",png_get_copyright(NULL));
4069
4070Also, the PNG logo (in PNG format, of course) is supplied in the
Glenn Randers-Pehrsona4d54bd2000-07-14 08:15:12 -0500[diff] [blame]4071files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]4072
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4073Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]4074certification mark of the Open Source Initiative.
4075
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4076Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]4077glennrp at users.sourceforge.net
Glenn Randers-Pehrson1916f6a2008-08-14 13:44:49 -0500[diff] [blame^]4078August 14, 2008
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]4079
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4080.\" end of man page
4081