source: trunk/src/3rdparty/libpng/libpng.3@ 885

Last change on this file since 885 was 846, checked in by Dmitry A. Kuminov, 14 years ago

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