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