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