Commit | Line | Data |
---|---|---|
a626cc03 | 1 | .TH LIBPNG 3 "January 14, 1999" |
c801d85f | 2 | .SH NAME |
a626cc03 | 3 | libpng \- Portable Network Graphics (PNG) Reference Library 1.0.3 - January 14, 1999 |
c801d85f KB |
4 | .SH SYNOPSIS |
5 | ||
6 | #include <png.h> | |
7 | ||
8 | int png_check_sig (png_bytep sig, int num); | |
9 | ||
10 | void png_chunk_error (png_structp png_ptr, png_const_charp | |
11 | error); | |
12 | ||
13 | void png_chunk_warning (png_structp png_ptr, png_const_charp | |
14 | message); | |
15 | ||
16 | void png_convert_from_struct_tm (png_timep ptime, struct tm FAR | |
17 | * ttime); | |
18 | ||
19 | void png_convert_from_time_t (png_timep ptime, time_t ttime); | |
20 | ||
21 | png_charp png_convert_to_rfc1123 (png_structp png_ptr, | |
22 | png_timep ptime); | |
23 | ||
24 | png_infop png_create_info_struct (png_structp png_ptr); | |
25 | ||
26 | png_structp png_create_read_struct (png_const_charp | |
27 | user_png_ver, voidp error_ptr, png_error_ptr error_fn, | |
28 | png_error_ptr warn_fn); | |
29 | ||
a626cc03 RR |
30 | png_structp png_create_read_struct_2(png_const_charp user_png_ver, |
31 | png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr | |
32 | warn_fn, png_voidp mem_ptr, png_malloc_ptr malloc_fn, | |
33 | png_free_ptr free_fn) | |
34 | ||
c801d85f KB |
35 | png_structp png_create_write_struct (png_const_charp |
36 | user_png_ver, voidp error_ptr, png_error_ptr error_fn, | |
37 | png_error_ptr warn_fn); | |
38 | ||
a626cc03 RR |
39 | png_structp png_create_write_struct_2(png_const_charp |
40 | user_png_ver, png_voidp error_ptr, png_error_ptr error_fn, | |
41 | png_error_ptr warn_fn, png_voidp mem_ptr, | |
42 | png_malloc_ptr malloc_fn, png_free_ptr free_fn) | |
43 | ||
44 | int png_debug(int level, png_const_charp message) | |
45 | ||
46 | int png_debug1(int level, png_const_charp message, p1) | |
c801d85f | 47 | |
a626cc03 | 48 | int png_debug2(int level, png_const_charp message, p1, p2) |
c801d85f KB |
49 | |
50 | void png_destroy_info_struct (png_structp png_ptr, png_infopp | |
51 | info_ptr_ptr); | |
52 | ||
53 | void png_destroy_read_struct (png_structpp png_ptr_ptr, | |
54 | png_infopp info_ptr_ptr, png_infopp end_info_ptr_ptr); | |
55 | ||
56 | void png_destroy_write_struct (png_structpp png_ptr_ptr, | |
57 | png_infopp info_ptr_ptr); | |
58 | ||
59 | void png_error (png_structp png_ptr, png_const_charp error); | |
60 | ||
61 | void png_free (png_structp png_ptr, png_voidp ptr); | |
62 | ||
a626cc03 RR |
63 | void png_free_default(png_structp png_ptr, png_voidp ptr) |
64 | ||
c801d85f KB |
65 | png_byte png_get_bit_depth (png_structp png_ptr, png_infop |
66 | info_ptr); | |
67 | ||
68 | png_uint_32 png_get_bKGD (png_structp png_ptr, png_infop | |
69 | info_ptr, png_color_16p *background); | |
70 | ||
71 | png_byte png_get_channels (png_structp png_ptr, png_infop | |
72 | info_ptr); | |
73 | ||
74 | png_uint_32 png_get_cHRM (png_structp png_ptr, png_infop | |
75 | info_ptr, double *white_x, double *white_y, double *red_x, | |
76 | double *red_y, double *green_x, double *green_y, double | |
77 | *blue_x, double *blue_y); | |
78 | ||
79 | png_byte png_get_color_type (png_structp png_ptr, png_infop | |
80 | info_ptr); | |
81 | ||
82 | png_byte png_get_compression_type (png_structp png_ptr, | |
83 | png_infop info_ptr); | |
84 | ||
a626cc03 RR |
85 | png_byte png_get_copyright (png_structp png_ptr); |
86 | ||
c801d85f KB |
87 | png_voidp png_get_error_ptr (png_structp png_ptr); |
88 | ||
89 | png_byte png_get_filter_type (png_structp png_ptr, png_infop | |
90 | info_ptr); | |
91 | ||
92 | png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop | |
93 | info_ptr, double *file_gamma); | |
94 | ||
a626cc03 RR |
95 | png_byte png_get_header_version (png_structp png_ptr); |
96 | ||
c801d85f KB |
97 | png_uint_32 png_get_hIST (png_structp png_ptr, png_infop |
98 | info_ptr, png_uint_16p *hist); | |
99 | ||
a626cc03 RR |
100 | png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop |
101 | info_ptr, png_uint_32 *width, png_uint_32 *height, int | |
102 | *bit_depth, int *color_type, int *interlace_type, int | |
103 | *compression_type, int *filter_type); | |
104 | ||
c801d85f KB |
105 | png_uint_32 png_get_image_height (png_structp png_ptr, |
106 | png_infop info_ptr); | |
107 | ||
108 | png_uint_32 png_get_image_width (png_structp png_ptr, png_infop | |
109 | info_ptr); | |
110 | ||
111 | png_byte png_get_interlace_type (png_structp png_ptr, png_infop | |
112 | info_ptr); | |
113 | ||
114 | png_voidp png_get_io_ptr (png_structp png_ptr); | |
115 | ||
a626cc03 | 116 | png_voidp png_get_mem_ptr(png_structp png_ptr) |
c801d85f KB |
117 | |
118 | png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop | |
119 | info_ptr, png_uint_32 *offset_x, png_uint_32 *offset_y, int | |
120 | *unit_type); | |
121 | ||
122 | png_uint_32 png_get_pCAL (png_structp png_ptr, png_infop | |
123 | info_ptr, png_charp *purpose, png_int_32 *X0, png_int_32 *X1, | |
124 | int *type, int *nparams, png_charp *units, png_charpp *params); | |
125 | ||
126 | png_uint_32 png_get_pHYs (png_structp png_ptr, png_infop | |
127 | info_ptr, png_uint_32 *res_x, png_uint_32 *res_y, int | |
128 | *unit_type); | |
129 | ||
130 | float png_get_pixel_aspect_ratio (png_structp png_ptr, | |
131 | png_infop info_ptr); | |
132 | ||
133 | png_uint_32 png_get_pixels_per_meter (png_structp png_ptr, | |
134 | png_infop info_ptr); | |
135 | ||
136 | png_voidp png_get_progressive_ptr (png_structp png_ptr); | |
137 | ||
138 | png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop | |
139 | info_ptr, png_colorp *palette, int *num_palette); | |
140 | ||
a626cc03 RR |
141 | png_byte png_get_rgb_to_gray_status (png_structp png_ptr) |
142 | ||
c801d85f KB |
143 | png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop |
144 | info_ptr); | |
145 | ||
146 | png_uint_32 png_get_sBIT (png_structp png_ptr, png_infop | |
147 | info_ptr, png_color_8p *sig_bit); | |
148 | ||
149 | png_bytep png_get_signature (png_structp png_ptr, png_infop | |
150 | info_ptr); | |
151 | ||
152 | png_uint_32 png_get_sRGB (png_structp png_ptr, png_infop | |
153 | info_ptr, int *intent); | |
154 | ||
155 | png_uint_32 png_get_text (png_structp png_ptr, png_infop | |
156 | info_ptr, png_textp *text_ptr, int *num_text); | |
157 | ||
158 | png_uint_32 png_get_tIME (png_structp png_ptr, png_infop | |
159 | info_ptr, png_timep *mod_time); | |
160 | ||
161 | png_uint_32 png_get_tRNS (png_structp png_ptr, png_infop | |
162 | info_ptr, png_bytep *trans, int *num_trans, png_color_16p | |
163 | *trans_values); | |
164 | ||
165 | png_uint_32 png_get_valid (png_structp png_ptr, png_infop | |
166 | info_ptr, png_uint_32 flag); | |
167 | ||
168 | png_uint_32 png_get_x_offset_microns (png_structp png_ptr, | |
169 | png_infop info_ptr); | |
170 | ||
171 | png_uint_32 png_get_x_offset_pixels (png_structp png_ptr, | |
172 | png_infop info_ptr); | |
173 | ||
174 | png_uint_32 png_get_x_pixels_per_meter (png_structp png_ptr, | |
175 | png_infop info_ptr); | |
176 | ||
177 | png_uint_32 png_get_y_offset_microns (png_structp png_ptr, | |
178 | png_infop info_ptr); | |
179 | ||
180 | png_uint_32 png_get_y_offset_pixels (png_structp png_ptr, | |
181 | png_infop info_ptr); | |
182 | ||
183 | png_uint_32 png_get_y_pixels_per_meter (png_structp png_ptr, | |
184 | png_infop info_ptr); | |
185 | ||
186 | void png_info_init (png_infop info_ptr); | |
187 | ||
188 | void png_init_io (png_structp png_ptr, FILE *fp); | |
189 | ||
190 | png_voidp png_malloc (png_structp png_ptr, png_uint_32 size); | |
191 | ||
a626cc03 RR |
192 | png_voidp png_malloc_default(png_structp png_ptr, |
193 | png_uint_32 size) | |
194 | ||
c801d85f KB |
195 | voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size); |
196 | ||
197 | png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1, | |
198 | png_voidp s2, png_uint_32 size); | |
199 | ||
200 | voidp png_memset (png_voidp s1, int value, png_size_t size); | |
201 | ||
202 | png_voidp png_memset_check (png_structp png_ptr, png_voidp | |
203 | s1, int value, png_uint_32 size); | |
204 | ||
205 | void png_process_data (png_structp png_ptr, png_infop info_ptr, | |
206 | png_bytep buffer, png_size_t buffer_size); | |
207 | ||
208 | void png_progressive_combine_row (png_structp png_ptr, | |
209 | png_bytep old_row, png_bytep new_row); | |
210 | ||
211 | void png_read_destroy (png_structp png_ptr, png_infop info_ptr, | |
212 | png_infop end_info_ptr); | |
213 | ||
214 | void png_read_end (png_structp png_ptr, png_infop info_ptr); | |
215 | ||
216 | void png_read_image (png_structp png_ptr, png_bytepp image); | |
217 | ||
218 | void png_read_info (png_structp png_ptr, png_infop info_ptr); | |
219 | ||
220 | void png_read_row (png_structp png_ptr, png_bytep row, | |
221 | png_bytep display_row); | |
222 | ||
223 | void png_read_rows (png_structp png_ptr, png_bytepp row, | |
224 | png_bytepp display_row, png_uint_32 num_rows); | |
225 | ||
226 | void png_read_update_info (png_structp png_ptr, png_infop | |
227 | info_ptr); | |
228 | ||
229 | void png_set_background (png_structp png_ptr, png_color_16p | |
230 | background_color, int background_gamma_code, int need_expand, | |
231 | double background_gamma); | |
232 | ||
233 | void png_set_bgr (png_structp png_ptr); | |
234 | ||
235 | void png_set_bKGD (png_structp png_ptr, png_infop info_ptr, | |
236 | png_color_16p background); | |
237 | ||
238 | void png_set_cHRM (png_structp png_ptr, png_infop info_ptr, | |
239 | double white_x, double white_y, double red_x, double red_y, | |
240 | double green_x, double green_y, double blue_x, double blue_y); | |
241 | ||
242 | void png_set_compression_level (png_structp png_ptr, int | |
243 | level); | |
244 | ||
245 | void png_set_compression_mem_level (png_structp png_ptr, int | |
246 | mem_level); | |
247 | ||
248 | void png_set_compression_method (png_structp png_ptr, int | |
249 | method); | |
250 | ||
251 | void png_set_compression_strategy (png_structp png_ptr, int | |
252 | strategy); | |
253 | ||
254 | void png_set_compression_window_bits (png_structp png_ptr, int | |
255 | window_bits); | |
256 | ||
257 | void png_set_crc_action (png_structp png_ptr, int crit_action, | |
258 | int ancil_action); | |
259 | ||
260 | void png_set_dither (png_structp png_ptr, png_colorp palette, | |
261 | int num_palette, int maximum_colors, png_uint_16p histogram, | |
262 | int full_dither); | |
263 | ||
264 | void png_set_error_fn (png_structp png_ptr, png_voidp | |
265 | error_ptr, png_error_ptr error_fn, png_error_ptr warning_fn); | |
266 | ||
267 | void png_set_expand (png_structp png_ptr); | |
268 | ||
269 | void png_set_filler (png_structp png_ptr, png_uint_32 filler, | |
270 | int flags); | |
271 | ||
272 | void png_set_filter (png_structp png_ptr, int method, int | |
273 | filters); | |
274 | ||
275 | void png_set_filter_heuristics (png_structp png_ptr, int | |
276 | heuristic_method, int num_weights, png_doublep filter_weights, | |
277 | png_doublep filter_costs); | |
278 | ||
279 | void png_set_flush (png_structp png_ptr, int nrows); | |
280 | ||
281 | void png_set_gamma (png_structp png_ptr, double screen_gamma, | |
282 | double default_file_gamma); | |
283 | ||
284 | void png_set_gAMA (png_structp png_ptr, png_infop info_ptr, | |
285 | double file_gamma); | |
286 | ||
287 | void png_set_gray_to_rgb (png_structp png_ptr); | |
288 | ||
289 | void png_set_hIST (png_structp png_ptr, png_infop info_ptr, | |
290 | png_uint_16p hist); | |
291 | ||
292 | int png_set_interlace_handling (png_structp png_ptr); | |
293 | ||
294 | void png_set_invert_alpha (png_structp png_ptr); | |
295 | ||
296 | void png_set_invert_mono (png_structp png_ptr); | |
297 | ||
298 | void png_set_IHDR (png_structp png_ptr, png_infop info_ptr, | |
299 | png_uint_32 width, png_uint_32 height, int bit_depth, int | |
300 | color_type, int interlace_type, int compression_type, int | |
301 | filter_type); | |
302 | ||
a626cc03 RR |
303 | void png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr, |
304 | png_malloc_ptr malloc_fn, png_free_ptr free_fn) | |
305 | ||
c801d85f KB |
306 | void png_set_oFFs (png_structp png_ptr, png_infop info_ptr, |
307 | png_uint_32 offset_x, png_uint_32 offset_y, int unit_type); | |
308 | ||
309 | void png_set_packing (png_structp png_ptr); | |
310 | ||
311 | void png_set_packswap (png_structp png_ptr); | |
312 | ||
313 | void png_set_pCAL (png_structp png_ptr, png_infop info_ptr, | |
314 | png_charp purpose, png_int_32 X0, png_int_32 X1, int type, int | |
315 | nparams, png_charp units, png_charpp params); | |
316 | ||
317 | void png_set_pHYs (png_structp png_ptr, png_infop info_ptr, | |
318 | png_uint_32 res_x, png_uint_32 res_y, int unit_type); | |
319 | ||
320 | void png_set_progressive_read_fn (png_structp png_ptr, | |
321 | png_voidp progressive_ptr, png_progressive_info_ptr info_fn, | |
322 | png_progressive_row_ptr row_fn, png_progressive_end_ptr | |
323 | end_fn); | |
324 | ||
325 | void png_set_PLTE (png_structp png_ptr, png_infop info_ptr, | |
326 | png_colorp palette, int num_palette); | |
327 | ||
328 | void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr, | |
329 | png_rw_ptr read_data_fn); | |
330 | ||
331 | void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr | |
a626cc03 | 332 | read_row_fn); |
c801d85f KB |
333 | |
334 | void png_set_read_user_transform_fn (png_structp png_ptr, | |
a626cc03 | 335 | png_user_transform_ptr read_user_transform_fn); |
c801d85f | 336 | |
a626cc03 | 337 | void png_set_rgb_to_gray (png_structp png_ptr, int error_action); |
c801d85f KB |
338 | |
339 | void png_set_sBIT (png_structp png_ptr, png_infop info_ptr, | |
340 | png_color_8p sig_bit); | |
341 | ||
342 | void png_set_shift (png_structp png_ptr, png_color_8p | |
343 | true_bits); | |
344 | ||
345 | void png_set_sig_bytes (png_structp png_ptr, int num_bytes); | |
346 | ||
347 | void png_set_sRGB (png_structp png_ptr, png_infop info_ptr, int | |
348 | intent); | |
349 | ||
350 | void png_set_sRGB_gAMA_and_cHRM (png_structp png_ptr, png_infop | |
351 | info_ptr, int intent); | |
352 | ||
353 | void png_set_strip_16 (png_structp png_ptr); | |
354 | ||
355 | void png_set_strip_alpha (png_structp png_ptr); | |
356 | ||
357 | void png_set_swap (png_structp png_ptr); | |
358 | ||
359 | void png_set_swap_alpha (png_structp png_ptr); | |
360 | ||
361 | void png_set_text (png_structp png_ptr, png_infop info_ptr, | |
362 | png_textp text_ptr, int num_text); | |
363 | ||
364 | void png_set_tIME (png_structp png_ptr, png_infop info_ptr, | |
365 | png_timep mod_time); | |
366 | ||
367 | void png_set_tRNS (png_structp png_ptr, png_infop info_ptr, | |
368 | png_bytep trans, int num_trans, png_color_16p trans_values); | |
369 | ||
370 | void png_set_write_fn (png_structp png_ptr, png_voidp io_ptr, | |
371 | png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn); | |
372 | ||
373 | void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr | |
a626cc03 | 374 | write_row_fn); |
c801d85f KB |
375 | |
376 | void png_set_write_user_transform_fn (png_structp png_ptr, | |
a626cc03 | 377 | png_user_transform_ptr write_user_transform_fn); |
c801d85f KB |
378 | |
379 | int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t | |
380 | num_to_check); | |
381 | ||
382 | void png_start_read_image (png_structp png_ptr); | |
383 | ||
384 | void png_warning (png_structp png_ptr, png_const_charp | |
385 | message); | |
386 | ||
387 | void png_write_chunk (png_structp png_ptr, png_bytep | |
388 | chunk_name, png_bytep data, png_size_t length); | |
389 | ||
390 | void png_write_chunk_data (png_structp png_ptr, png_bytep data, | |
391 | png_size_t length); | |
392 | ||
393 | void png_write_chunk_end (png_structp png_ptr); | |
394 | ||
395 | void png_write_chunk_start (png_structp png_ptr, png_bytep | |
396 | chunk_name, png_uint_32 length); | |
397 | ||
398 | void png_write_destroy (png_structp png_ptr); | |
399 | ||
400 | void png_write_destroy_info (png_infop info_ptr); | |
401 | ||
402 | void png_write_end (png_structp png_ptr, png_infop info_ptr); | |
403 | ||
404 | void png_write_flush (png_structp png_ptr); | |
a626cc03 | 405 | |
c801d85f KB |
406 | void png_write_image (png_structp png_ptr, png_bytepp image); |
407 | ||
408 | void png_write_info (png_structp png_ptr, png_infop info_ptr); | |
409 | ||
410 | void png_write_row (png_structp png_ptr, png_bytep row); | |
411 | ||
412 | void png_write_rows (png_structp png_ptr, png_bytepp row, | |
413 | png_uint_32 num_rows); | |
414 | ||
415 | .SH DESCRIPTION | |
416 | The | |
417 | .I libpng | |
418 | library supports encoding, decoding, and various manipulations of | |
419 | the Portable Network Graphics (PNG) format image files. It uses the | |
420 | .IR zlib(3) | |
421 | compression library. | |
422 | Following is a copy of the libpng.txt file that accompanies libpng. | |
423 | .SH LIBPNG.TXT | |
424 | libpng.txt - A description on how to use and modify libpng | |
425 | ||
a626cc03 | 426 | libpng version 1.0.3 - January 14, 1999 |
c801d85f KB |
427 | Updated and distributed by Glenn Randers-Pehrson |
428 | <randeg@alumni.rpi.edu> | |
a626cc03 | 429 | Copyright (c) 1998, 1999 Glenn Randers-Pehrson |
c801d85f KB |
430 | For conditions of distribution and use, see copyright |
431 | notice in png.h. | |
432 | ||
433 | based on: | |
434 | ||
435 | libpng 1.0 beta 6 version 0.96 May 28, 1997 | |
a626cc03 | 436 | Updated and distributed by Andreas Dilger |
c801d85f KB |
437 | Copyright (c) 1996, 1997 Andreas Dilger |
438 | ||
439 | libpng 1.0 beta 2 - version 0.88 January 26, 1996 | |
440 | For conditions of distribution and use, see copyright | |
441 | notice in png.h. Copyright (c) 1995, 1996 Guy Eric | |
442 | Schalnat, Group 42, Inc. | |
443 | ||
444 | Updated/rewritten per request in the libpng FAQ | |
445 | Copyright (c) 1995 Frank J. T. Wojcik | |
446 | December 18, 1995 && January 20, 1996 | |
447 | ||
448 | .SH I. Introduction | |
449 | ||
450 | This file describes how to use and modify the PNG reference library | |
451 | (known as libpng) for your own use. There are five sections to this | |
452 | file: introduction, structures, reading, writing, and modification and | |
453 | configuration notes for various special platforms. In addition to this | |
454 | file, example.c is a good starting point for using the library, as | |
455 | it is heavily commented and should include everything most people | |
456 | will need. We assume that libpng is already installed; see the | |
457 | INSTALL file for instructions on how to install libpng. | |
458 | ||
459 | Libpng was written as a companion to the PNG specification, as a way | |
460 | of reducing the amount of time and effort it takes to support the PNG | |
461 | file format in application programs. The PNG specification is available | |
462 | as RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as a | |
463 | W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some | |
464 | additional chunks are described in the special-purpose public chunks | |
465 | documents at <ftp://ftp.uu.net/graphics/png/documents/>. Other information | |
a626cc03 RR |
466 | about PNG, and the latest version of libpng, can be found at the PNG home |
467 | page, <http://www.cdrom.com/pub/png/>. | |
c801d85f KB |
468 | |
469 | Most users will not have to modify the library significantly; advanced | |
470 | users may want to modify it more. All attempts were made to make it as | |
471 | complete as possible, while keeping the code easy to understand. | |
472 | Currently, this library only supports C. Support for other languages | |
473 | is being considered. | |
474 | ||
475 | Libpng has been designed to handle multiple sessions at one time, | |
476 | to be easily modifiable, to be portable to the vast majority of | |
477 | machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy | |
478 | to use. The ultimate goal of libpng is to promote the acceptance of | |
479 | the PNG file format in whatever way possible. While there is still | |
480 | work to be done (see the TODO file), libpng should cover the | |
481 | majority of the needs of its users. | |
482 | ||
483 | Libpng uses zlib for its compression and decompression of PNG files. | |
a626cc03 RR |
484 | Further information about zlib, and the latest version of zlib, can |
485 | be found at the zlib home page, <http://www.cdrom.com/pub/infozip/zlib/>. | |
c801d85f KB |
486 | The zlib compression utility is a general purpose utility that is |
487 | useful for more than PNG files, and can be used without libpng. | |
488 | See the documentation delivered with zlib for more details. | |
489 | You can usually find the source files for the zlib utility wherever you | |
490 | find the libpng source files. | |
491 | ||
492 | Libpng is thread safe, provided the threads are using different | |
493 | instances of the structures. Each thread should have its own | |
494 | png_struct and png_info instances, and thus its own image. | |
495 | Libpng does not protect itself against two threads using the | |
496 | same instance of a structure. | |
497 | ||
498 | ||
499 | .SH II. Structures | |
500 | ||
501 | There are two main structures that are important to libpng, png_struct | |
502 | and png_info. The first, png_struct, is an internal structure that | |
503 | will not, for the most part, be used by a user except as the first | |
504 | variable passed to every libpng function call. | |
505 | ||
506 | The png_info structure is designed to provide information about the | |
507 | PNG file. At one time, the fields of png_info were intended to be | |
508 | directly accessible to the user. However, this tended to cause problems | |
509 | with applications using dynamically loaded libraries, and as a result | |
510 | a set of interface functions for png_info was developed. The fields | |
511 | of png_info are still available for older applications, but it is | |
512 | suggested that applications use the new interfaces if at all possible. | |
513 | ||
514 | The png.h header file is an invaluable reference for programming with libpng. | |
515 | And while I'm on the topic, make sure you include the libpng header file: | |
516 | ||
517 | #include <png.h> | |
518 | ||
519 | .SH III. Reading | |
520 | ||
521 | Reading PNG files: | |
522 | ||
523 | We'll now walk you through the possible functions to call when reading | |
524 | in a PNG file, briefly explaining the syntax and purpose of each one. | |
525 | See example.c and png.h for more detail. While Progressive reading | |
526 | is covered in the next section, you will still need some of the | |
527 | functions discussed in this section to read a PNG file. | |
528 | ||
529 | You will want to do the I/O initialization(*) before you get into libpng, | |
530 | so if it doesn't work, you don't have much to undo. Of course, you | |
531 | will also want to insure that you are, in fact, dealing with a PNG | |
532 | file. Libpng provides a simple check to see if a file is a PNG file. | |
533 | To use it, pass in the first 1 to 8 bytes of the file, and it will | |
534 | return true or false (1 or 0) depending on whether the bytes could be | |
535 | part of a PNG file. Of course, the more bytes you pass in, the | |
536 | greater the accuracy of the prediction. | |
537 | ||
538 | If you are intending to keep the file pointer open for use in libpng, | |
539 | you must ensure you don't read more than 8 bytes from the beginning | |
540 | of the file, and you also have to make a call to png_set_sig_bytes_read() | |
541 | with the number of bytes you read from the beginning. Libpng will | |
542 | then only check the bytes (if any) that your program didn't read. | |
543 | ||
544 | (*): If you are not using the standard I/O functions, you will need | |
545 | to replace them with custom functions. See the discussion under | |
546 | Customizing libpng. | |
547 | ||
548 | ||
549 | FILE *fp = fopen(file_name, "rb"); | |
550 | if (!fp) | |
551 | { | |
552 | return; | |
553 | } | |
554 | fread(header, 1, number, fp); | |
a626cc03 | 555 | is_png = !png_sig_cmp(header, 0, number); |
c801d85f KB |
556 | if (!is_png) |
557 | { | |
558 | return; | |
559 | } | |
560 | ||
561 | ||
562 | Next, png_struct and png_info need to be allocated and initialized. In | |
563 | order to ensure that the size of these structures is correct even with a | |
564 | dynamically linked libpng, there are functions to initialize and | |
565 | allocate the structures. We also pass the library version, optional | |
566 | pointers to error handling functions, and a pointer to a data struct for | |
567 | use by the error functions, if necessary (the pointer and functions can | |
568 | be NULL if the default error handlers are to be used). See the section | |
569 | on Changes to Libpng below regarding the old initialization functions. | |
570 | ||
571 | png_structp png_ptr = png_create_read_struct | |
a626cc03 | 572 | (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, |
c801d85f KB |
573 | user_error_fn, user_warning_fn); |
574 | if (!png_ptr) | |
575 | return; | |
576 | ||
577 | png_infop info_ptr = png_create_info_struct(png_ptr); | |
578 | if (!info_ptr) | |
579 | { | |
580 | png_destroy_read_struct(&png_ptr, | |
581 | (png_infopp)NULL, (png_infopp)NULL); | |
582 | return; | |
583 | } | |
584 | ||
585 | png_infop end_info = png_create_info_struct(png_ptr); | |
586 | if (!end_info) | |
587 | { | |
588 | png_destroy_read_struct(&png_ptr, &info_ptr, | |
589 | (png_infopp)NULL); | |
590 | return; | |
591 | } | |
592 | ||
a626cc03 RR |
593 | If you want to use your own memory allocation routines, |
594 | define PNG_USER_MEM_SUPPORTED and use | |
595 | png_create_read_struct_2() instead of png_create_read_struct(): | |
596 | ||
597 | png_structp png_ptr = png_create_read_struct_2 | |
598 | (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, | |
599 | user_error_fn, user_warning_fn, (png_voidp) | |
600 | user_mem_ptr, user_malloc_fn, user_free_fn); | |
601 | ||
602 | The error handling routines passed to png_create_read_struct() | |
603 | and the memory alloc/free routines passed to png_create_struct_2() | |
604 | are only necessary if you are not using the libpng supplied error | |
605 | handling and memory alloc/free functions. | |
c801d85f | 606 | |
a626cc03 RR |
607 | When libpng encounters an error, it expects to longjmp back |
608 | to your routine. Therefore, you will need to call setjmp and pass | |
609 | your png_ptr->jmpbuf. If you read the file from different | |
c801d85f KB |
610 | routines, you will need to update the jmpbuf field every time you enter |
611 | a new routine that will call a png_ function. | |
612 | ||
613 | See your documentation of setjmp/longjmp for your compiler for more | |
614 | handling in the Customizing Libpng section below for more information on | |
615 | the libpng error handling. If an error occurs, and libpng longjmp's | |
616 | back to your setjmp, you will want to call png_destroy_read_struct() to | |
617 | free any memory. | |
618 | ||
619 | if (setjmp(png_ptr->jmpbuf)) | |
620 | { | |
621 | png_destroy_read_struct(&png_ptr, &info_ptr, | |
622 | &end_info); | |
623 | fclose(fp); | |
624 | return; | |
625 | } | |
626 | ||
627 | Now you need to set up the input code. The default for libpng is to | |
628 | use the C function fread(). If you use this, you will need to pass a | |
629 | valid FILE * in the function png_init_io(). Be sure that the file is | |
630 | opened in binary mode. If you wish to handle reading data in another | |
631 | way, you need not call the png_init_io() function, but you must then | |
632 | implement the libpng I/O methods discussed in the Customizing Libpng | |
633 | section below. | |
634 | ||
635 | png_init_io(png_ptr, fp); | |
636 | ||
637 | If you had previously opened the file and read any of the signature from | |
638 | the beginning in order to see if this was a PNG file, you need to let | |
639 | libpng know that there are some bytes missing from the start of the file. | |
640 | ||
641 | png_set_sig_bytes(png_ptr, number); | |
642 | ||
643 | At this point, you can set up a callback function that will be | |
644 | called after each row has been read, which you can use to control | |
645 | a progress meter or the like. It's demonstrated in pngtest.c. | |
646 | You must supply a function | |
647 | ||
648 | void read_row_callback(png_ptr, png_uint_32 row, int pass); | |
649 | { | |
650 | /* put your code here */ | |
651 | } | |
652 | ||
653 | (You can give it another name that you like instead of "read_row_callback") | |
654 | ||
655 | To inform libpng about your function, use | |
656 | ||
657 | png_set_read_status_fn(png_ptr, read_row_callback); | |
658 | ||
659 | In PNG files, the alpha channel in an image is the level of opacity. | |
660 | If you need the alpha channel in an image to be the level of transparency | |
661 | instead of opacity, you can invert the alpha channel (or the tRNS chunk | |
662 | data) after it's read, so that 0 is fully opaque and 255 (in 8-bit or | |
663 | paletted images) or 65535 (in 16-bit images) is fully transparent, with | |
664 | ||
665 | png_set_invert_alpha(png_ptr); | |
666 | ||
667 | This has to appear here rather than later with the other transformations | |
668 | because the tRNS chunk data must be modified in the case of paletted images. | |
669 | If your image is not a paletted image, the tRNS data (which in such cases | |
670 | represents a single color to be rendered as transparent) won't be changed. | |
671 | ||
672 | Finally, you can write your own transformation function if none of | |
673 | the existing ones meets your needs. This is done by setting a callback | |
674 | with | |
675 | ||
676 | png_set_read_user_transform_fn(png_ptr, | |
677 | read_transform_fn); | |
678 | ||
679 | You must supply the function | |
680 | ||
681 | void read_transform_fn(png_ptr ptr, row_info_ptr | |
a626cc03 | 682 | row_info, png_bytep data) |
c801d85f KB |
683 | |
684 | See pngtest.c for a working example. Your function will be called | |
685 | after all of the other transformations have been processed. | |
686 | ||
687 | You are now ready to read all the file information up to the actual | |
688 | image data. You do this with a call to png_read_info(). | |
689 | ||
690 | png_read_info(png_ptr, info_ptr); | |
691 | ||
692 | Functions are used to get the information from the info_ptr: | |
693 | ||
694 | png_get_IHDR(png_ptr, info_ptr, &width, &height, | |
695 | &bit_depth, &color_type, &interlace_type, | |
696 | &compression_type, &filter_type); | |
697 | ||
698 | width - holds the width of the image | |
699 | in pixels (up to 2^31). | |
700 | height - holds the height of the image | |
701 | in pixels (up to 2^31). | |
702 | bit_depth - holds the bit depth of one of the | |
703 | image channels. (valid values are | |
704 | 1, 2, 4, 8, 16 and depend also on | |
705 | the color_type. See also | |
706 | significant bits (sBIT) below). | |
707 | color_type - describes which color/alpha channels | |
708 | are present. | |
709 | PNG_COLOR_TYPE_GRAY | |
710 | (bit depths 1, 2, 4, 8, 16) | |
a626cc03 | 711 | PNG_COLOR_TYPE_GRAY_ALPHA |
c801d85f KB |
712 | (bit depths 8, 16) |
713 | PNG_COLOR_TYPE_PALETTE | |
714 | (bit depths 1, 2, 4, 8) | |
715 | PNG_COLOR_TYPE_RGB | |
716 | (bit_depths 8, 16) | |
717 | PNG_COLOR_TYPE_RGB_ALPHA | |
718 | (bit_depths 8, 16) | |
719 | ||
720 | PNG_COLOR_MASK_PALETTE | |
721 | PNG_COLOR_MASK_COLOR | |
722 | PNG_COLOR_MASK_ALPHA | |
723 | ||
724 | filter_type - (must be PNG_FILTER_TYPE_BASE | |
725 | for PNG 1.0) | |
726 | compression_type - (must be PNG_COMPRESSION_TYPE_BASE | |
727 | for PNG 1.0) | |
728 | interlace_type - (PNG_INTERLACE_NONE or | |
729 | PNG_INTERLACE_ADAM7) | |
730 | Any or all of interlace_type, compression_type, of | |
731 | filter_type can be | |
732 | NULL if you are not interested in their values. | |
733 | ||
734 | channels = png_get_channels(png_ptr, info_ptr); | |
735 | channels - number of channels of info for the | |
736 | color type (valid values are 1 (GRAY, | |
737 | PALETTE), 2 (GRAY_ALPHA), 3 (RGB), | |
738 | 4 (RGB_ALPHA or RGB + filler byte)) | |
739 | rowbytes = png_get_rowbytes(png_ptr, info_ptr); | |
740 | rowbytes - number of bytes needed to hold a row | |
741 | ||
742 | signature = png_get_signature(png_ptr, info_ptr); | |
743 | signature - holds the signature read from the | |
744 | file (if any). The data is kept in | |
745 | the same offset it would be if the | |
746 | whole signature were read (i.e. if an | |
747 | application had already read in 4 | |
748 | bytes of signature before starting | |
749 | libpng, the remaining 4 bytes would | |
750 | be in signature[4] through signature[7] | |
751 | (see png_set_sig_bytes())). | |
752 | ||
753 | ||
754 | width = png_get_image_width(png_ptr, | |
755 | info_ptr); | |
756 | height = png_get_image_height(png_ptr, | |
757 | info_ptr); | |
758 | bit_depth = png_get_bit_depth(png_ptr, | |
759 | info_ptr); | |
760 | color_type = png_get_color_type(png_ptr, | |
761 | info_ptr); | |
762 | filter_type = png_get_filter_type(png_ptr, | |
763 | info_ptr); | |
764 | compression_type = png_get_compression_type(png_ptr, | |
765 | info_ptr); | |
766 | interlace_type = png_get_interlace_type(png_ptr, | |
767 | info_ptr); | |
768 | ||
769 | ||
770 | These are also important, but their validity depends on whether the chunk | |
771 | has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and | |
772 | png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the | |
773 | data has been read, or zero if it is missing. The parameters to the | |
774 | png_get_<chunk> are set directly if they are simple data types, or a pointer | |
775 | into the info_ptr is returned for any complex types. | |
776 | ||
777 | png_get_PLTE(png_ptr, info_ptr, &palette, | |
778 | &num_palette); | |
779 | palette - the palette for the file | |
780 | (array of png_color) | |
781 | num_palette - number of entries in the palette | |
782 | ||
783 | png_get_gAMA(png_ptr, info_ptr, &gamma); | |
784 | gamma - the gamma the file is written | |
785 | at (PNG_INFO_gAMA) | |
786 | ||
787 | png_get_sRGB(png_ptr, info_ptr, &srgb_intent); | |
788 | srgb_intent - the rendering intent (PNG_INFO_sRGB) | |
789 | The presence of the sRGB chunk | |
790 | means that the pixel data is in the | |
791 | sRGB color space. This chunk also | |
792 | implies specific values of gAMA and | |
793 | cHRM. | |
794 | ||
795 | png_get_sBIT(png_ptr, info_ptr, &sig_bit); | |
796 | sig_bit - the number of significant bits for | |
797 | (PNG_INFO_sBIT) each of the gray, | |
798 | red, green, and blue channels, | |
799 | whichever are appropriate for the | |
800 | given color type (png_color_16) | |
801 | ||
802 | png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans, | |
803 | &trans_values); | |
804 | trans - array of transparent entries for | |
805 | palette (PNG_INFO_tRNS) | |
806 | trans_values - transparent pixel for non-paletted | |
807 | images (PNG_INFO_tRNS) | |
808 | num_trans - number of transparent entries | |
809 | (PNG_INFO_tRNS) | |
810 | ||
811 | png_get_hIST(png_ptr, info_ptr, &hist); | |
812 | (PNG_INFO_hIST) | |
813 | hist - histogram of palette (array of | |
814 | png_color_16) | |
815 | ||
816 | png_get_tIME(png_ptr, info_ptr, &mod_time); | |
817 | mod_time - time image was last modified | |
818 | (PNG_VALID_tIME) | |
819 | ||
820 | png_get_bKGD(png_ptr, info_ptr, &background); | |
821 | background - background color (PNG_VALID_bKGD) | |
822 | ||
823 | num_text = png_get_text(png_ptr, info_ptr, &text_ptr); | |
824 | text_ptr - array of png_text holding image | |
825 | comments | |
826 | text_ptr[i]->key - keyword for comment. | |
827 | text_ptr[i]->text - text comments for current | |
828 | keyword. | |
829 | text_ptr[i]->compression - type of compression used | |
830 | on "text" PNG_TEXT_COMPRESSION_NONE | |
831 | or PNG_TEXT_COMPRESSION_zTXt | |
832 | num_text - number of comments | |
833 | ||
834 | png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y, | |
835 | &unit_type); | |
836 | offset_x - positive offset from the left edge | |
837 | of the screen | |
838 | offset_y - positive offset from the top edge | |
839 | of the screen | |
840 | unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER | |
841 | ||
842 | png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y, | |
843 | &unit_type); | |
844 | res_x - pixels/unit physical resolution in | |
845 | x direction | |
846 | res_y - pixels/unit physical resolution in | |
847 | x direction | |
848 | unit_type - PNG_RESOLUTION_UNKNOWN, | |
849 | PNG_RESOLUTION_METER | |
850 | ||
851 | The data from the pHYs chunk can be retrieved in several convenient | |
852 | forms: | |
853 | ||
854 | res_x = png_get_x_pixels_per_meter(png_ptr, | |
855 | info_ptr) | |
856 | res_y = png_get_y_pixels_per_meter(png_ptr, | |
857 | info_ptr) | |
858 | res_x_and_y = png_get_pixels_per_meter(png_ptr, | |
859 | info_ptr) | |
860 | aspect_ratio = png_get_pixel_aspect_ratio(png_ptr, | |
861 | info_ptr) | |
862 | ||
863 | (Each of these returns 0 [signifying "unknown"] if | |
864 | the data is not present or if res_x is 0; | |
865 | res_x_and_y is 0 if res_x != res_y) | |
866 | ||
867 | For more information, see the png_info definition in png.h and the | |
868 | PNG specification for chunk contents. Be careful with trusting | |
869 | rowbytes, as some of the transformations could increase the space | |
870 | needed to hold a row (expand, filler, gray_to_rgb, etc.). | |
871 | See png_read_update_info(), below. | |
872 | ||
873 | A quick word about text_ptr and num_text. PNG stores comments in | |
874 | keyword/text pairs, one pair per chunk, with no limit on the number | |
875 | of text chunks, and a 2^31 byte limit on their size. While there are | |
876 | suggested keywords, there is no requirement to restrict the use to these | |
877 | strings. It is strongly suggested that keywords and text be sensible | |
878 | to humans (that's the point), so don't use abbreviations. Non-printing | |
879 | symbols are not allowed. See the PNG specification for more details. | |
880 | There is also no requirement to have text after the keyword. | |
881 | ||
882 | Keywords should be limited to 79 Latin-1 characters without leading or | |
883 | trailing spaces, but non-consecutive spaces are allowed within the | |
884 | keyword. It is possible to have the same keyword any number of times. | |
885 | The text_ptr is an array of png_text structures, each holding pointer | |
886 | to a keyword and a pointer to a text string. Only the text string may | |
887 | be null. The keyword/text pairs are put into the array in the order | |
888 | that they are received. However, some or all of the text chunks may be | |
889 | after the image, so, to make sure you have read all the text chunks, | |
890 | don't mess with these until after you read the stuff after the image. | |
891 | This will be mentioned again below in the discussion that goes with | |
892 | png_read_end(). | |
893 | ||
894 | After you've read the header information, you can set up the library | |
895 | to handle any special transformations of the image data. The various | |
896 | ways to transform the data will be described in the order that they | |
897 | should occur. This is important, as some of these change the color | |
898 | type and/or bit depth of the data, and some others only work on | |
899 | certain color types and bit depths. Even though each transformation | |
900 | checks to see if it has data that it can do something with, you should | |
901 | make sure to only enable a transformation if it will be valid for the | |
902 | data. For example, don't swap red and blue on grayscale data. | |
903 | ||
904 | The colors used for the background and transparency values should be | |
905 | supplied in the same format/depth as the current image data. They | |
906 | are stored in the same format/depth as the image data in a bKGD or tRNS | |
907 | chunk, so this is what libpng expects for this data. The colors are | |
908 | transformed to keep in sync with the image data when an application | |
909 | calls the png_read_update_info() routine (see below). | |
910 | ||
911 | Data will be decoded into the supplied row buffers packed into bytes | |
912 | unless the library has been told to transform it into another format. | |
913 | For example, 4 bit/pixel paletted or grayscale data will be returned | |
914 | 2 pixels/byte with the leftmost pixel in the high-order bits of the | |
915 | byte, unless png_set_packing() is called. 8-bit RGB data will be stored | |
a626cc03 | 916 | in RGB RGB RGB format unless png_set_filler() is called to insert filler |
c801d85f | 917 | bytes, either before or after each RGB triplet. 16-bit RGB data will |
a626cc03 | 918 | be returned RRGGBB RRGGBB, with the most significant byte of the color |
c801d85f | 919 | value first, unless png_set_strip_16() is called to transform it to |
a626cc03 RR |
920 | regular RGB RGB triplets, or png_set_filler() is called to insert |
921 | filler bytes, either before or after each RRGGBB triplet. Similarly, | |
922 | 8-bit or 16-bit grayscale data can be modified with png_set_filler() | |
923 | or png_set_strip_16(). | |
c801d85f KB |
924 | |
925 | The following code transforms grayscale images of less than 8 to 8 bits, | |
926 | changes paletted images to RGB, and adds a full alpha channel if there is | |
927 | transparency information in a tRNS chunk. This is most useful on | |
928 | grayscale images with bit depths of 2 or 4 or if there is a multiple-image | |
929 | viewing application that wishes to treat all images in the same way. | |
930 | ||
931 | if (color_type == PNG_COLOR_TYPE_PALETTE && | |
932 | bit_depth <= 8) png_set_expand(png_ptr); | |
933 | ||
934 | if (color_type == PNG_COLOR_TYPE_GRAY && | |
935 | bit_depth < 8) png_set_expand(png_ptr); | |
936 | ||
937 | if (png_get_valid(png_ptr, info_ptr, | |
938 | PNG_INFO_tRNS)) png_set_expand(png_ptr); | |
939 | ||
940 | PNG can have files with 16 bits per channel. If you only can handle | |
941 | 8 bits per channel, this will strip the pixels down to 8 bit. | |
942 | ||
943 | if (bit_depth == 16) | |
944 | png_set_strip_16(png_ptr); | |
945 | ||
946 | The png_set_background() function tells libpng to composite images | |
947 | with alpha or simple transparency against the supplied background | |
948 | color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), | |
949 | you may use this color, or supply another color more suitable for | |
950 | the current display (e.g., the background color from a web page). You | |
951 | need to tell libpng whether the color is in the gamma space of the | |
952 | display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file | |
953 | (PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one | |
954 | that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't | |
955 | know why anyone would use this, but it's here). | |
956 | ||
957 | If, for some reason, you don't need the alpha channel on an image, | |
958 | and you want to remove it rather than combining it with the background | |
959 | (but the image author certainly had in mind that you *would* combine | |
960 | it with the background, so that's what you should probably do): | |
961 | ||
962 | if (color_type & PNG_COLOR_MASK_ALPHA) | |
963 | png_set_strip_alpha(png_ptr); | |
964 | ||
965 | PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as | |
966 | they can, resulting in, for example, 8 pixels per byte for 1 bit | |
967 | files. This code expands to 1 pixel per byte without changing the | |
968 | values of the pixels: | |
969 | ||
970 | if (bit_depth < 8) | |
971 | png_set_packing(png_ptr); | |
972 | ||
973 | PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels | |
974 | stored in a PNG image have been "scaled" or "shifted" up to the next | |
975 | higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to | |
976 | 8 bits/sample in the range [0, 255]). However, it is also possible to | |
977 | convert the PNG pixel data back to the original bit depth of the image. | |
978 | This call reduces the pixels back down to the original bit depth: | |
979 | ||
980 | png_color_16p sig_bit; | |
981 | ||
982 | if (png_get_sBIT(png_ptr, info_ptr, &sig_bit)) | |
983 | png_set_shift(png_ptr, sig_bit); | |
984 | ||
985 | PNG files store 3-color pixels in red, green, blue order. This code | |
986 | changes the storage of the pixels to blue, green, red: | |
987 | ||
988 | if (color_type == PNG_COLOR_TYPE_RGB || | |
989 | color_type == PNG_COLOR_TYPE_RGB_ALPHA) | |
990 | png_set_bgr(png_ptr); | |
991 | ||
992 | PNG files store RGB pixels packed into 3 bytes. This code expands them | |
993 | into 4 bytes for windowing systems that need them in this format: | |
994 | ||
995 | if (bit_depth == 8 && color_type == | |
996 | PNG_COLOR_TYPE_RGB) png_set_filler(png_ptr, | |
997 | filler, PNG_FILLER_BEFORE); | |
998 | ||
a626cc03 | 999 | where "filler" is the 8 or 16-bit number to fill with, and the location is |
c801d85f KB |
1000 | either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether |
1001 | you want the filler before the RGB or after. This transformation | |
1002 | does not affect images that already have full alpha channels. | |
1003 | ||
1004 | If you are reading an image with an alpha channel, and you need the | |
1005 | data as ARGB instead of the normal PNG format RGBA: | |
1006 | ||
1007 | if (color_type == PNG_COLOR_TYPE_RGB_ALPHA) | |
1008 | png_set_swap_alpha(png_ptr); | |
1009 | ||
1010 | For some uses, you may want a grayscale image to be represented as | |
1011 | RGB. This code will do that conversion: | |
1012 | ||
1013 | if (color_type == PNG_COLOR_TYPE_GRAY || | |
1014 | color_type == PNG_COLOR_TYPE_GRAY_ALPHA) | |
1015 | png_set_gray_to_rgb(png_ptr); | |
1016 | ||
a626cc03 RR |
1017 | Conversely, you can convert an RGB or RGBA image to grayscale or grayscale |
1018 | with alpha. This is intended for conversion of images that really are | |
1019 | gray (red == green == blue), so the function simply strips out the red | |
1020 | and blue channels, leaving the green channel in the gray position. | |
1021 | ||
1022 | if (color_type == PNG_COLOR_TYPE_RGB || | |
1023 | color_type == PNG_COLOR_TYPE_RGB_ALPHA) | |
1024 | png_set_rgb_to_gray(png_ptr, error_action, | |
1025 | float red_weight, float green_weight); | |
1026 | ||
1027 | error_action = 1: silently do the conversion | |
1028 | error_action = 2: issue a warning if the original | |
1029 | image has any pixel where | |
1030 | red != green or red != blue | |
1031 | error_action = 3: issue an error and abort the | |
1032 | conversion if the original | |
1033 | image has any pixel where | |
1034 | red != green or red != blue | |
1035 | ||
1036 | red_weight: weight of red component | |
1037 | (NULL -> default 54/256) | |
1038 | green_weight: weight of green component | |
1039 | (NULL -> default 183/256) | |
1040 | ||
1041 | If you have set error_action = 1 or 2, you can | |
1042 | later check whether the image really was gray, after processing | |
1043 | the image rows, with the png_get_rgb_to_gray_status(png_ptr) function. | |
1044 | It will return a png_byte that is zero if the image was gray or | |
1045 | 1 if there were any non-gray pixels. bKGD and sBIT data | |
1046 | will be silently converted to grayscale, using the green channel | |
1047 | data, regardless of the error_action setting. | |
1048 | ||
1049 | With 0.0<=red_weight+green_weight<=1.0, | |
1050 | the normalized graylevel is computed: | |
1051 | ||
1052 | int rw = red_weight * 256; | |
1053 | int gw = green_weight * 256; | |
1054 | int bw = 256 - (rw + gw); | |
1055 | gray = (rw*red + gw*green + bw*blue)/256; | |
1056 | ||
1057 | The default values approximate those recommended in the Charles | |
1058 | Poynton's Color FAQ, <http://www.inforamp.net/~poynton/> | |
1059 | Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net | |
1060 | ||
1061 | Y = 0.212671 * R + 0.715160 * G + 0.072169 * B | |
1062 | ||
1063 | Libpng approximates this with | |
1064 | ||
1065 | Y = 0.211 * R + 0.715 * G + 0.074 * B | |
1066 | ||
1067 | which can be expressed with integers as | |
1068 | ||
1069 | Y = (54 * R + 183 * G + 19 * B)/256 | |
1070 | ||
1071 | The calculation is done in a linear colorspace, if the image gamma | |
1072 | is known. | |
1073 | ||
c801d85f | 1074 | If you have a grayscale and you are using png_set_expand() to change to |
a626cc03 RR |
1075 | a higher bit-depth, you must either supply the background color as a gray |
1076 | value at the original file bit-depth (need_expand = 1) or else supply the | |
1077 | background color as an RGB triplet at the final, expanded bit depth | |
1078 | (need_expand = 0). Similarly, if you are reading a paletted image, you | |
1079 | must either supply the background color as a palette index (need_expand = 1) | |
1080 | or as an RGB triplet that may or may not be in the palette (need_expand = 0). | |
c801d85f KB |
1081 | |
1082 | png_color_16 my_background; | |
1083 | png_color_16p image_background; | |
1084 | ||
a626cc03 RR |
1085 | if (png_get_bKGD(png_ptr, info_ptr, &image_background)) |
1086 | png_set_background(png_ptr, image_background, | |
1087 | PNG_BACKGROUND_GAMMA_FILE, 1, 1.0); | |
c801d85f KB |
1088 | else |
1089 | png_set_background(png_ptr, &my_background, | |
1090 | PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0); | |
1091 | ||
1092 | To properly display PNG images on any kind of system, the application needs | |
1093 | to know what the display gamma is. Ideally, the user will know this, and | |
1094 | the application will allow them to set it. One method of allowing the user | |
1095 | to set the display gamma separately for each system is to check for the | |
1096 | DISPLAY_GAMMA and VIEWING_GAMMA environment variables or for a SCREEN_GAMMA | |
1097 | environment variable, which will hopefully be correctly set. | |
1098 | ||
1099 | Note that display_gamma is the gamma of your display, while screen_gamma is | |
1100 | the overall gamma correction required to produce pleasing results, | |
1101 | which depends on the lighting conditions in the surrounding environment. | |
1102 | Screen_gamma is display_gamma/viewing_gamma, where viewing_gamma is | |
1103 | the amount of additional gamma correction needed to compensate for | |
1104 | a (viewing_gamma=1.25) environment. In a dim or brightly lit room, no | |
1105 | compensation other than the display_gamma is needed (viewing_gamma=1.0). | |
1106 | ||
1107 | if (/* We have a user-defined screen | |
1108 | gamma value */) | |
1109 | { | |
1110 | screen_gamma = user_defined_screen_gamma; | |
1111 | } | |
1112 | /* One way that applications can share the same | |
1113 | screen gamma value */ | |
1114 | else if ((gamma_str = getenv("SCREEN_GAMMA")) | |
1115 | != NULL) | |
1116 | { | |
1117 | screen_gamma = atof(gamma_str); | |
1118 | } | |
1119 | /* If we don't have another value */ | |
1120 | else | |
1121 | { | |
1122 | screen_gamma = 2.2; /* A good guess for a | |
1123 | PC monitor in a bright office or a dim room */ | |
1124 | screen_gamma = 2.0; /* A good guess for a | |
1125 | PC monitor in a dark room */ | |
1126 | screen_gamma = 1.7 or 1.0; /* A good | |
1127 | guess for Mac systems */ | |
1128 | } | |
1129 | ||
1130 | The png_set_gamma() function handles gamma transformations of the data. | |
1131 | Pass both the file gamma and the current screen_gamma. If the file does | |
1132 | not have a gamma value, you can pass one anyway if you have an idea what | |
a626cc03 | 1133 | it is (usually 0.45455 is a good guess for GIF images on PCs). Note |
c801d85f KB |
1134 | that file gammas are inverted from screen gammas. See the discussions |
1135 | on gamma in the PNG specification for an excellent description of what | |
1136 | gamma is, and why all applications should support it. It is strongly | |
1137 | recommended that PNG viewers support gamma correction. | |
1138 | ||
1139 | if (png_get_gAMA(png_ptr, info_ptr, &gamma)) | |
1140 | png_set_gamma(png_ptr, screen_gamma, gamma); | |
1141 | else | |
a626cc03 | 1142 | png_set_gamma(png_ptr, screen_gamma, 0.45455); |
c801d85f KB |
1143 | |
1144 | If you need to reduce an RGB file to a paletted file, or if a paletted | |
1145 | file has more entries then will fit on your screen, png_set_dither() | |
1146 | will do that. Note that this is a simple match dither that merely | |
1147 | finds the closest color available. This should work fairly well with | |
1148 | optimized palettes, and fairly badly with linear color cubes. If you | |
1149 | pass a palette that is larger then maximum_colors, the file will | |
1150 | reduce the number of colors in the palette so it will fit into | |
1151 | maximum_colors. If there is a histogram, it will use it to make | |
1152 | more intelligent choices when reducing the palette. If there is no | |
1153 | histogram, it may not do as good a job. | |
1154 | ||
1155 | if (color_type & PNG_COLOR_MASK_COLOR) | |
1156 | { | |
1157 | if (png_get_valid(png_ptr, info_ptr, | |
1158 | PNG_INFO_PLTE)) | |
1159 | { | |
1160 | png_color_16p histogram; | |
1161 | ||
1162 | png_get_hIST(png_ptr, info_ptr, | |
1163 | &histogram); | |
1164 | png_set_dither(png_ptr, palette, num_palette, | |
1165 | max_screen_colors, histogram, 1); | |
1166 | } | |
1167 | else | |
1168 | { | |
1169 | png_color std_color_cube[MAX_SCREEN_COLORS] = | |
1170 | { ... colors ... }; | |
1171 | ||
1172 | png_set_dither(png_ptr, std_color_cube, | |
1173 | MAX_SCREEN_COLORS, MAX_SCREEN_COLORS, | |
1174 | NULL,0); | |
1175 | } | |
1176 | } | |
1177 | ||
1178 | PNG files describe monochrome as black being zero and white being one. | |
1179 | The following code will reverse this (make black be one and white be | |
1180 | zero): | |
1181 | ||
1182 | if (bit_depth == 1 && color_type == PNG_COLOR_GRAY) | |
1183 | png_set_invert_mono(png_ptr); | |
1184 | ||
1185 | PNG files store 16 bit pixels in network byte order (big-endian, | |
1186 | ie. most significant bits first). This code changes the storage to the | |
1187 | other way (little-endian, i.e. least significant bits first, the | |
1188 | way PCs store them): | |
1189 | ||
1190 | if (bit_depth == 16) | |
1191 | png_set_swap(png_ptr); | |
1192 | ||
1193 | If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you | |
1194 | need to change the order the pixels are packed into bytes, you can use: | |
1195 | ||
1196 | if (bit_depth < 8) | |
1197 | png_set_packswap(png_ptr); | |
1198 | ||
1199 | The last thing to handle is interlacing; this is covered in detail below, | |
1200 | but you must call the function here if you want libpng to handle expansion | |
1201 | of the interlaced image. | |
1202 | ||
1203 | number_of_passes = png_set_interlace_handling(png_ptr); | |
1204 | ||
1205 | After setting the transformations, libpng can update your png_info | |
1206 | structure to reflect any transformations you've requested with this | |
1207 | call. This is most useful to update the info structure's rowbytes | |
1208 | field so you can use it to allocate your image memory. This function | |
1209 | will also update your palette with the correct screen_gamma and | |
1210 | background if these have been given with the calls above. | |
1211 | ||
1212 | png_read_update_info(png_ptr, info_ptr); | |
1213 | ||
1214 | After you call png_read_update_info(), you can allocate any | |
1215 | memory you need to hold the image. The row data is simply | |
1216 | raw byte data for all forms of images. As the actual allocation | |
1217 | varies among applications, no example will be given. If you | |
1218 | are allocating one large chunk, you will need to build an | |
1219 | array of pointers to each row, as it will be needed for some | |
1220 | of the functions below. | |
1221 | ||
1222 | After you've allocated memory, you can read the image data. | |
1223 | The simplest way to do this is in one function call. If you are | |
1224 | allocating enough memory to hold the whole image, you can just | |
1225 | call png_read_image() and libpng will read in all the image data | |
1226 | and put it in the memory area supplied. You will need to pass in | |
1227 | an array of pointers to each row. | |
1228 | ||
1229 | This function automatically handles interlacing, so you don't need | |
1230 | to call png_set_interlace_handling() or call this function multiple | |
1231 | times, or any of that other stuff necessary with png_read_rows(). | |
1232 | ||
1233 | png_read_image(png_ptr, row_pointers); | |
1234 | ||
1235 | where row_pointers is: | |
1236 | ||
1237 | png_bytep row_pointers[height]; | |
1238 | ||
1239 | You can point to void or char or whatever you use for pixels. | |
1240 | ||
1241 | If you don't want to read in the whole image at once, you can | |
1242 | use png_read_rows() instead. If there is no interlacing (check | |
1243 | interlace_type == PNG_INTERLACE_NONE), this is simple: | |
1244 | ||
1245 | png_read_rows(png_ptr, row_pointers, NULL, | |
1246 | number_of_rows); | |
1247 | ||
1248 | where row_pointers is the same as in the png_read_image() call. | |
1249 | ||
1250 | If you are doing this just one row at a time, you can do this with | |
1251 | row_pointers: | |
1252 | ||
1253 | png_bytep row_pointers = row; | |
1254 | png_read_row(png_ptr, &row_pointers, NULL); | |
1255 | ||
1256 | If the file is interlaced (info_ptr->interlace_type != 0), things get | |
1257 | somewhat harder. The only current (PNG Specification version 1.0) | |
1258 | interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7) | |
1259 | is a somewhat complicated 2D interlace scheme, known as Adam7, that | |
1260 | breaks down an image into seven smaller images of varying size, based | |
1261 | on an 8x8 grid. | |
1262 | ||
1263 | libpng can fill out those images or it can give them to you "as is". | |
1264 | If you want them filled out, there are two ways to do that. The one | |
1265 | mentioned in the PNG specification is to expand each pixel to cover | |
1266 | those pixels that have not been read yet (the "rectangle" method). | |
1267 | This results in a blocky image for the first pass, which gradually | |
1268 | smooths out as more pixels are read. The other method is the "sparkle" | |
1269 | method, where pixels are drawn only in their final locations, with the | |
1270 | rest of the image remaining whatever colors they were initialized to | |
1271 | before the start of the read. The first method usually looks better, | |
1272 | but tends to be slower, as there are more pixels to put in the rows. | |
1273 | ||
1274 | If you don't want libpng to handle the interlacing details, just call | |
1275 | png_read_rows() seven times to read in all seven images. Each of the | |
1276 | images is a valid image by itself, or they can all be combined on an | |
1277 | 8x8 grid to form a single image (although if you intend to combine them | |
1278 | you would be far better off using the libpng interlace handling). | |
1279 | ||
1280 | The first pass will return an image 1/8 as wide as the entire image | |
1281 | (every 8th column starting in column 0) and 1/8 as high as the original | |
1282 | (every 8th row starting in row 0), the second will be 1/8 as wide | |
1283 | (starting in column 4) and 1/8 as high (also starting in row 0). The | |
1284 | third pass will be 1/4 as wide (every 4th pixel starting in column 0) and | |
1285 | 1/8 as high (every 8th row starting in row 4), and the fourth pass will | |
1286 | be 1/4 as wide and 1/4 as high (every 4th column starting in column 2, | |
1287 | and every 4th row starting in row 0). The fifth pass will return an | |
1288 | image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2), | |
1289 | while the sixth pass will be 1/2 as wide and 1/2 as high as the original | |
1290 | (starting in column 1 and row 0). The seventh and final pass will be as | |
1291 | wide as the original, and 1/2 as high, containing all of the odd | |
1292 | numbered scanlines. Phew! | |
1293 | ||
1294 | If you want libpng to expand the images, call this before calling | |
1295 | png_start_read_image() or png_read_update_info(): | |
1296 | ||
1297 | if (interlace_type == PNG_INTERLACE_ADAM7) | |
1298 | number_of_passes | |
1299 | = png_set_interlace_handling(png_ptr); | |
1300 | ||
1301 | This will return the number of passes needed. Currently, this | |
1302 | is seven, but may change if another interlace type is added. | |
1303 | This function can be called even if the file is not interlaced, | |
1304 | where it will return one pass. | |
1305 | ||
1306 | If you are not going to display the image after each pass, but are | |
1307 | going to wait until the entire image is read in, use the sparkle | |
1308 | effect. This effect is faster and the end result of either method | |
1309 | is exactly the same. If you are planning on displaying the image | |
1310 | after each pass, the "rectangle" effect is generally considered the | |
1311 | better looking one. | |
1312 | ||
1313 | If you only want the "sparkle" effect, just call png_read_rows() as | |
1314 | normal, with the third parameter NULL. Make sure you make pass over | |
1315 | the image number_of_passes times, and you don't change the data in the | |
1316 | rows between calls. You can change the locations of the data, just | |
1317 | not the data. Each pass only writes the pixels appropriate for that | |
1318 | pass, and assumes the data from previous passes is still valid. | |
1319 | ||
1320 | png_read_rows(png_ptr, row_pointers, NULL, | |
1321 | number_of_rows); | |
1322 | ||
1323 | If you only want the first effect (the rectangles), do the same as | |
1324 | before except pass the row buffer in the third parameter, and leave | |
1325 | the second parameter NULL. | |
1326 | ||
1327 | png_read_rows(png_ptr, NULL, row_pointers, | |
1328 | number_of_rows); | |
1329 | ||
1330 | After you are finished reading the image, you can finish reading | |
1331 | the file. If you are interested in comments or time, which may be | |
1332 | stored either before or after the image data, you should pass the | |
1333 | separate png_info struct if you want to keep the comments from | |
1334 | before and after the image separate. If you are not interested, you | |
1335 | can pass NULL. | |
1336 | ||
1337 | png_read_end(png_ptr, end_info); | |
1338 | ||
1339 | When you are done, you can free all memory allocated by libpng like this: | |
1340 | ||
1341 | png_destroy_read_struct(&png_ptr, &info_ptr, | |
1342 | &end_info); | |
1343 | ||
1344 | For a more compact example of reading a PNG image, see the file example.c. | |
1345 | ||
1346 | ||
1347 | Reading PNG files progressively: | |
1348 | ||
1349 | The progressive reader is slightly different then the non-progressive | |
1350 | reader. Instead of calling png_read_info(), png_read_rows(), and | |
1351 | png_read_end(), you make one call to png_process_data(), which calls | |
1352 | callbacks when it has the info, a row, or the end of the image. You | |
1353 | set up these callbacks with png_set_progressive_read_fn(). You don't | |
1354 | have to worry about the input/output functions of libpng, as you are | |
1355 | giving the library the data directly in png_process_data(). I will | |
1356 | assume that you have read the section on reading PNG files above, | |
1357 | so I will only highlight the differences (although I will show | |
1358 | all of the code). | |
1359 | ||
1360 | png_structp png_ptr; | |
1361 | png_infop info_ptr; | |
1362 | ||
1363 | /* An example code fragment of how you would | |
1364 | initialize the progressive reader in your | |
1365 | application. */ | |
1366 | int | |
1367 | initialize_png_reader() | |
1368 | { | |
1369 | png_ptr = png_create_read_struct | |
a626cc03 | 1370 | (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, |
c801d85f KB |
1371 | user_error_fn, user_warning_fn); |
1372 | if (!png_ptr) | |
1373 | return -1; | |
1374 | info_ptr = png_create_info_struct(png_ptr); | |
1375 | if (!info_ptr) | |
1376 | { | |
1377 | png_destroy_read_struct(&png_ptr, (png_infopp)NULL, | |
1378 | (png_infopp)NULL); | |
1379 | return -1; | |
1380 | } | |
1381 | ||
1382 | if (setjmp(png_ptr->jmpbuf)) | |
1383 | { | |
1384 | png_destroy_read_struct(&png_ptr, &info_ptr, | |
1385 | (png_infopp)NULL); | |
1386 | return -1; | |
1387 | } | |
1388 | ||
1389 | /* This one's new. You can provide functions | |
1390 | to be called when the header info is valid, | |
1391 | when each row is completed, and when the image | |
1392 | is finished. If you aren't using all functions, | |
a626cc03 RR |
1393 | you can specify NULL parameters. Even when all |
1394 | three functions are NULL, you need to call | |
1395 | png_set_progressive_read_fn(). You can use | |
c801d85f KB |
1396 | any struct as the user_ptr (cast to a void pointer |
1397 | for the function call), and retrieve the pointer | |
1398 | from inside the callbacks using the function | |
1399 | ||
1400 | png_get_progressive_ptr(png_ptr); | |
1401 | ||
1402 | which will return a void pointer, which you have | |
1403 | to cast appropriately. | |
1404 | */ | |
1405 | png_set_progressive_read_fn(png_ptr, (void *)user_ptr, | |
1406 | info_callback, row_callback, end_callback); | |
1407 | ||
1408 | return 0; | |
1409 | } | |
1410 | ||
1411 | /* A code fragment that you call as you receive blocks | |
1412 | of data */ | |
1413 | int | |
1414 | process_data(png_bytep buffer, png_uint_32 length) | |
1415 | { | |
1416 | if (setjmp(png_ptr->jmpbuf)) | |
1417 | { | |
1418 | png_destroy_read_struct(&png_ptr, &info_ptr, | |
1419 | (png_infopp)NULL); | |
1420 | return -1; | |
1421 | } | |
1422 | ||
1423 | /* This one's new also. Simply give it a chunk | |
1424 | of data from the file stream (in order, of | |
1425 | course). On machines with segmented memory | |
1426 | models machines, don't give it any more than | |
a626cc03 | 1427 | 64K. The library seems to run fine with sizes |
c801d85f KB |
1428 | of 4K. Although you can give it much less if |
1429 | necessary (I assume you can give it chunks of | |
1430 | 1 byte, I haven't tried less then 256 bytes | |
1431 | yet). When this function returns, you may | |
1432 | want to display any rows that were generated | |
1433 | in the row callback if you don't already do | |
a626cc03 | 1434 | so there. |
c801d85f KB |
1435 | */ |
1436 | png_process_data(png_ptr, info_ptr, buffer, length); | |
1437 | return 0; | |
1438 | } | |
1439 | ||
1440 | /* This function is called (as set by | |
a626cc03 | 1441 | png_set_progressive_read_fn() above) when enough data |
c801d85f KB |
1442 | has been supplied so all of the header has been |
1443 | read. | |
1444 | */ | |
1445 | void | |
1446 | info_callback(png_structp png_ptr, png_infop info) | |
1447 | { | |
1448 | /* Do any setup here, including setting any of | |
1449 | the transformations mentioned in the Reading | |
1450 | PNG files section. For now, you _must_ call | |
1451 | either png_start_read_image() or | |
1452 | png_read_update_info() after all the | |
1453 | transformations are set (even if you don't set | |
1454 | any). You may start getting rows before | |
1455 | png_process_data() returns, so this is your | |
1456 | last chance to prepare for that. | |
1457 | */ | |
1458 | } | |
1459 | ||
1460 | /* This function is called when each row of image | |
1461 | data is complete */ | |
1462 | void | |
1463 | row_callback(png_structp png_ptr, png_bytep new_row, | |
1464 | png_uint_32 row_num, int pass) | |
1465 | { | |
1466 | /* If the image is interlaced, and you turned | |
1467 | on the interlace handler, this function will | |
1468 | be called for every row in every pass. Some | |
1469 | of these rows will not be changed from the | |
1470 | previous pass. When the row is not changed, | |
1471 | the new_row variable will be NULL. The rows | |
1472 | and passes are called in order, so you don't | |
1473 | really need the row_num and pass, but I'm | |
1474 | supplying them because it may make your life | |
1475 | easier. | |
1476 | ||
1477 | For the non-NULL rows of interlaced images, | |
1478 | you must call png_progressive_combine_row() | |
1479 | passing in the row and the old row. You can | |
1480 | call this function for NULL rows (it will just | |
1481 | return) and for non-interlaced images (it just | |
1482 | does the memcpy for you) if it will make the | |
1483 | code easier. Thus, you can just do this for | |
1484 | all cases: | |
1485 | */ | |
1486 | ||
1487 | png_progressive_combine_row(png_ptr, old_row, | |
1488 | new_row); | |
1489 | ||
1490 | /* where old_row is what was displayed for | |
a626cc03 RR |
1491 | previously for the row. Note that the first |
1492 | pass (pass == 0, really) will completely cover | |
c801d85f KB |
1493 | the old row, so the rows do not have to be |
1494 | initialized. After the first pass (and only | |
1495 | for interlaced images), you will have to pass | |
1496 | the current row, and the function will combine | |
1497 | the old row and the new row. | |
a626cc03 | 1498 | */ |
c801d85f KB |
1499 | } |
1500 | ||
1501 | void | |
1502 | end_callback(png_structp png_ptr, png_infop info) | |
1503 | { | |
1504 | /* This function is called after the whole image | |
1505 | has been read, including any chunks after the | |
1506 | image (up to and including the IEND). You | |
1507 | will usually have the same info chunk as you | |
1508 | had in the header, although some data may have | |
1509 | been added to the comments and time fields. | |
1510 | ||
1511 | Most people won't do much here, perhaps setting | |
1512 | a flag that marks the image as finished. | |
1513 | */ | |
1514 | } | |
1515 | ||
a626cc03 RR |
1516 | |
1517 | ||
c801d85f KB |
1518 | .SH IV. Writing |
1519 | ||
1520 | Much of this is very similar to reading. However, everything of | |
1521 | importance is repeated here, so you won't have to constantly look | |
1522 | back up in the reading section to understand writing. | |
1523 | ||
1524 | You will want to do the I/O initialization before you get into libpng, | |
1525 | so if it doesn't work, you don't have anything to undo. If you are not | |
1526 | using the standard I/O functions, you will need to replace them with | |
1527 | custom writing functions. See the discussion under Customizing libpng. | |
a626cc03 | 1528 | |
c801d85f KB |
1529 | FILE *fp = fopen(file_name, "wb"); |
1530 | if (!fp) | |
1531 | { | |
1532 | return; | |
1533 | } | |
1534 | ||
1535 | Next, png_struct and png_info need to be allocated and initialized. | |
1536 | As these can be both relatively large, you may not want to store these | |
1537 | on the stack, unless you have stack space to spare. Of course, you | |
1538 | will want to check if they return NULL. If you are also reading, | |
1539 | you won't want to name your read structure and your write structure | |
1540 | both "png_ptr"; you can call them anything you like, such as | |
1541 | "read_ptr" and "write_ptr". Look at pngtest.c, for example. | |
1542 | ||
1543 | png_structp png_ptr = png_create_write_struct | |
a626cc03 | 1544 | (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, |
c801d85f KB |
1545 | user_error_fn, user_warning_fn); |
1546 | if (!png_ptr) | |
1547 | return; | |
1548 | ||
1549 | png_infop info_ptr = png_create_info_struct(png_ptr); | |
1550 | if (!info_ptr) | |
1551 | { | |
1552 | png_destroy_write_struct(&png_ptr, | |
1553 | (png_infopp)NULL); | |
1554 | return; | |
1555 | } | |
1556 | ||
a626cc03 RR |
1557 | If you want to use your own memory allocation routines, |
1558 | define PNG_USER_MEM_SUPPORTED and use | |
1559 | png_create_write_struct_2() instead of png_create_read_struct(): | |
1560 | ||
1561 | png_structp png_ptr = png_create_write_struct_2 | |
1562 | (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, | |
1563 | user_error_fn, user_warning_fn, (png_voidp) | |
1564 | user_mem_ptr, user_malloc_fn, user_free_fn); | |
1565 | ||
c801d85f KB |
1566 | After you have these structures, you will need to set up the |
1567 | error handling. When libpng encounters an error, it expects to | |
1568 | longjmp() back to your routine. Therefore, you will need to call | |
a626cc03 | 1569 | setjmp() and pass the png_ptr->jmpbuf. If you |
c801d85f KB |
1570 | write the file from different routines, you will need to update |
1571 | the jmpbuf field every time you enter a new routine that will | |
1572 | call a png_ function. See your documentation of setjmp/longjmp | |
1573 | for your compiler for more information on setjmp/longjmp. See | |
1574 | the discussion on libpng error handling in the Customizing Libpng | |
1575 | section below for more information on the libpng error handling. | |
a626cc03 | 1576 | |
c801d85f | 1577 | if (setjmp(png_ptr->jmpbuf)) |
a626cc03 | 1578 | { |
c801d85f KB |
1579 | png_destroy_write_struct(&png_ptr, &info_ptr); |
1580 | fclose(fp); | |
1581 | return; | |
1582 | } | |
a626cc03 RR |
1583 | ... |
1584 | return; | |
c801d85f KB |
1585 | |
1586 | Now you need to set up the output code. The default for libpng is to | |
1587 | use the C function fwrite(). If you use this, you will need to pass a | |
1588 | valid FILE * in the function png_init_io(). Be sure that the file is | |
1589 | opened in binary mode. Again, if you wish to handle writing data in | |
1590 | another way, see the discussion on libpng I/O handling in the Customizing | |
1591 | Libpng section below. | |
1592 | ||
1593 | png_init_io(png_ptr, fp); | |
1594 | ||
1595 | At this point, you can set up a callback function that will be | |
1596 | called after each row has been written, which you can use to control | |
1597 | a progress meter or the like. It's demonstrated in pngtest.c. | |
1598 | You must supply a function | |
1599 | ||
1600 | void write_row_callback(png_ptr, png_uint_32 row, int pass); | |
1601 | { | |
1602 | /* put your code here */ | |
1603 | } | |
1604 | ||
1605 | (You can give it another name that you like instead of "write_row_callback") | |
1606 | ||
1607 | To inform libpng about your function, use | |
1608 | ||
1609 | png_set_write_status_fn(png_ptr, write_row_callback); | |
1610 | ||
1611 | You now have the option of modifying how the compression library will | |
1612 | run. The following functions are mainly for testing, but may be useful | |
1613 | in some cases, like if you need to write PNG files extremely fast and | |
1614 | are willing to give up some compression, or if you want to get the | |
1615 | maximum possible compression at the expense of slower writing. If you | |
1616 | have no special needs in this area, let the library do what it wants by | |
1617 | not calling this function at all, as it has been tuned to deliver a good | |
1618 | speed/compression ratio. The second parameter to png_set_filter() is | |
1619 | the filter method, for which the only valid value is '0' (as of the | |
1620 | October 1996 PNG specification, version 1.0). The third parameter is a | |
a626cc03 RR |
1621 | flag that indicates which filter type(s) are to be tested for each |
1622 | scanline. See the Compression Library for details on the specific filter | |
1623 | types. | |
1624 | ||
c801d85f | 1625 | |
c801d85f KB |
1626 | /* turn on or off filtering, and/or choose |
1627 | specific filters */ | |
1628 | png_set_filter(png_ptr, 0, | |
1629 | PNG_FILTER_NONE | PNG_FILTER_SUB | | |
1630 | PNG_FILTER_PAETH); | |
1631 | ||
1632 | The png_set_compression_???() functions interface to the zlib compression | |
1633 | library, and should mostly be ignored unless you really know what you are | |
1634 | doing. The only generally useful call is png_set_compression_level() | |
1635 | which changes how much time zlib spends on trying to compress the image | |
1636 | data. See the Compression Library for details on the compression levels. | |
1637 | ||
1638 | /* set the zlib compression level */ | |
1639 | png_set_compression_level(png_ptr, | |
1640 | Z_BEST_COMPRESSION); | |
1641 | ||
1642 | /* set other zlib parameters */ | |
1643 | png_set_compression_mem_level(png_ptr, 8); | |
1644 | png_set_compression_strategy(png_ptr, | |
1645 | Z_DEFAULT_STRATEGY); | |
1646 | png_set_compression_window_bits(png_ptr, 15); | |
1647 | png_set_compression_method(png_ptr, 8); | |
1648 | ||
1649 | You now need to fill in the png_info structure with all the data you | |
1650 | wish to write before the actual image. Note that the only thing you | |
1651 | are allowed to write after the image is the text chunks and the time | |
1652 | chunk (as of PNG Specification 1.0, anyway). See png_write_end() and | |
1653 | the latest PNG specification for more information on that. If you | |
1654 | wish to write them before the image, fill them in now, and flag that | |
1655 | data as being valid. If you want to wait until after the data, don't | |
1656 | fill them until png_write_end(). For all the fields in png_info and | |
1657 | their data types, see png.h. For explanations of what the fields | |
1658 | contain, see the PNG specification. | |
1659 | ||
1660 | Some of the more important parts of the png_info are: | |
1661 | ||
1662 | png_set_IHDR(png_ptr, info_ptr, width, height, | |
1663 | bit_depth, color_type, interlace_type, | |
1664 | compression_type, filter_type) | |
1665 | width - holds the width of the image | |
1666 | in pixels (up to 2^31). | |
1667 | height - holds the height of the image | |
1668 | in pixels (up to 2^31). | |
1669 | bit_depth - holds the bit depth of one of the | |
1670 | image channels. | |
1671 | (valid values are 1, 2, 4, 8, 16 | |
1672 | and depend also on the | |
1673 | color_type. See also significant | |
1674 | bits (sBIT) below). | |
1675 | color_type - describes which color/alpha | |
1676 | channels are present. | |
1677 | PNG_COLOR_TYPE_GRAY | |
1678 | (bit depths 1, 2, 4, 8, 16) | |
1679 | PNG_COLOR_TYPE_GRAY_ALPHA | |
1680 | (bit depths 8, 16) | |
1681 | PNG_COLOR_TYPE_PALETTE | |
1682 | (bit depths 1, 2, 4, 8) | |
1683 | PNG_COLOR_TYPE_RGB | |
1684 | (bit_depths 8, 16) | |
1685 | PNG_COLOR_TYPE_RGB_ALPHA | |
1686 | (bit_depths 8, 16) | |
1687 | ||
1688 | PNG_COLOR_MASK_PALETTE | |
1689 | PNG_COLOR_MASK_COLOR | |
1690 | PNG_COLOR_MASK_ALPHA | |
1691 | ||
1692 | interlace_type - PNG_INTERLACE_NONE or | |
1693 | PNG_INTERLACE_ADAM7 | |
1694 | compression_type - (must be | |
1695 | PNG_COMPRESSION_TYPE_DEFAULT) | |
1696 | filter_type - (must be PNG_FILTER_TYPE_DEFAULT) | |
1697 | ||
1698 | png_set_PLTE(png_ptr, info_ptr, palette, | |
1699 | num_palette); | |
1700 | palette - the palette for the file | |
1701 | (array of png_color) | |
1702 | num_palette - number of entries in the palette | |
1703 | ||
1704 | png_set_gAMA(png_ptr, info_ptr, gamma); | |
1705 | gamma - the gamma the image was created | |
1706 | at (PNG_INFO_gAMA) | |
1707 | ||
1708 | png_set_sRGB(png_ptr, info_ptr, srgb_intent); | |
1709 | srgb_intent - the rendering intent | |
1710 | (PNG_INFO_sRGB) The presence of | |
1711 | the sRGB chunk means that the pixel | |
1712 | data is in the sRGB color space. | |
1713 | This chunk also implies specific | |
1714 | values of gAMA and cHRM. Rendering | |
1715 | intent is the CSS-1 property that | |
1716 | has been defined by the International | |
1717 | Color Consortium | |
1718 | (http://www.color.org). | |
1719 | It can be one of | |
1720 | PNG_SRGB_INTENT_SATURATION, | |
1721 | PNG_SRGB_INTENT_PERCEPTUAL, | |
1722 | PNG_SRGB_INTENT_ABSOLUTE, or | |
1723 | PNG_SRGB_INTENT_RELATIVE. | |
a626cc03 | 1724 | |
c801d85f KB |
1725 | |
1726 | png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr, | |
1727 | srgb_intent); | |
1728 | srgb_intent - the rendering intent | |
1729 | (PNG_INFO_sRGB) The presence of the | |
1730 | sRGB chunk means that the pixel | |
1731 | data is in the sRGB color space. | |
1732 | This function also causes gAMA and | |
1733 | cHRM chunks with the specific values | |
1734 | that are consistent with sRGB to be | |
1735 | written. | |
1736 | ||
1737 | png_set_sBIT(png_ptr, info_ptr, sig_bit); | |
1738 | sig_bit - the number of significant bits for | |
1739 | (PNG_INFO_sBIT) each of the gray, red, | |
1740 | green, and blue channels, whichever are | |
1741 | appropriate for the given color type | |
1742 | (png_color_16) | |
1743 | ||
1744 | png_set_tRNS(png_ptr, info_ptr, trans, num_trans, | |
1745 | trans_values); | |
1746 | trans - array of transparent entries for | |
1747 | palette (PNG_INFO_tRNS) | |
1748 | trans_values - transparent pixel for non-paletted | |
1749 | images (PNG_INFO_tRNS) | |
1750 | num_trans - number of transparent entries | |
1751 | (PNG_INFO_tRNS) | |
1752 | ||
1753 | png_set_hIST(png_ptr, info_ptr, hist); | |
1754 | (PNG_INFO_hIST) | |
1755 | hist - histogram of palette (array of | |
1756 | png_color_16) | |
1757 | ||
1758 | png_set_tIME(png_ptr, info_ptr, mod_time); | |
1759 | mod_time - time image was last modified | |
1760 | (PNG_VALID_tIME) | |
1761 | ||
1762 | png_set_bKGD(png_ptr, info_ptr, background); | |
1763 | background - background color (PNG_VALID_bKGD) | |
1764 | ||
1765 | png_set_text(png_ptr, info_ptr, text_ptr, num_text); | |
1766 | text_ptr - array of png_text holding image | |
1767 | comments | |
1768 | text_ptr[i]->key - keyword for comment. | |
1769 | text_ptr[i]->text - text comments for current | |
1770 | keyword. | |
1771 | text_ptr[i]->compression - type of compression used | |
1772 | on "text" PNG_TEXT_COMPRESSION_NONE or | |
1773 | PNG_TEXT_COMPRESSION_zTXt | |
1774 | num_text - number of comments in text_ptr | |
1775 | ||
1776 | png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y, | |
1777 | unit_type); | |
1778 | offset_x - positive offset from the left | |
1779 | edge of the screen | |
1780 | offset_y - positive offset from the top | |
1781 | edge of the screen | |
1782 | unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER | |
1783 | ||
1784 | png_set_pHYs(png_ptr, info_ptr, res_x, res_y, | |
1785 | unit_type); | |
1786 | res_x - pixels/unit physical resolution | |
1787 | in x direction | |
1788 | res_y - pixels/unit physical resolution | |
1789 | in y direction | |
1790 | unit_type - PNG_RESOLUTION_UNKNOWN, | |
1791 | PNG_RESOLUTION_METER | |
1792 | ||
1793 | In PNG files, the alpha channel in an image is the level of opacity. | |
1794 | If your data is supplied as a level of transparency, you can invert the | |
1795 | alpha channel before you write it, so that 0 is fully transparent and 255 | |
1796 | (in 8-bit or paletted images) or 65535 (in 16-bit images) is fully opaque, | |
1797 | with | |
1798 | ||
1799 | png_set_invert_alpha(png_ptr); | |
1800 | ||
1801 | This must appear here instead of later with the other transformations | |
1802 | because in the case of paletted images the tRNS chunk data has to | |
1803 | be inverted before the tRNS chunk is written. If your image is not a | |
1804 | paletted image, the tRNS data (which in such cases represents a single | |
1805 | color to be rendered as transparent) won't be changed. | |
1806 | ||
1807 | A quick word about text and num_text. text is an array of png_text | |
1808 | structures. num_text is the number of valid structures in the array. | |
1809 | If you want, you can use max_text to hold the size of the array, but | |
1810 | libpng ignores it for writing (it does use it for reading). Each | |
1811 | png_text structure holds a keyword-text value, and a compression type. | |
1812 | The compression types have the same valid numbers as the compression | |
1813 | types of the image data. Currently, the only valid number is zero. | |
1814 | However, you can store text either compressed or uncompressed, unlike | |
a626cc03 | 1815 | images, which always have to be compressed. So if you don't want the |
c801d85f KB |
1816 | text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE. |
1817 | Until text gets around 1000 bytes, it is not worth compressing it. | |
1818 | After the text has been written out to the file, the compression type | |
1819 | is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR, | |
1820 | so that it isn't written out again at the end (in case you are calling | |
1821 | png_write_end() with the same struct. | |
1822 | ||
1823 | The keywords that are given in the PNG Specification are: | |
1824 | ||
1825 | Title Short (one line) title or | |
1826 | caption for image | |
1827 | Author Name of image's creator | |
1828 | Description Description of image (possibly long) | |
1829 | Copyright Copyright notice | |
1830 | Creation Time Time of original image creation | |
1831 | (usually RFC 1123 format, see below) | |
1832 | Software Software used to create the image | |
1833 | Disclaimer Legal disclaimer | |
1834 | Warning Warning of nature of content | |
1835 | Source Device used to create the image | |
1836 | Comment Miscellaneous comment; conversion | |
1837 | from other image format | |
1838 | ||
1839 | The keyword-text pairs work like this. Keywords should be short | |
1840 | simple descriptions of what the comment is about. Some typical | |
1841 | keywords are found in the PNG specification, as is some recommendations | |
1842 | on keywords. You can repeat keywords in a file. You can even write | |
1843 | some text before the image and some after. For example, you may want | |
1844 | to put a description of the image before the image, but leave the | |
1845 | disclaimer until after, so viewers working over modem connections | |
1846 | don't have to wait for the disclaimer to go over the modem before | |
1847 | they start seeing the image. Finally, keywords should be full | |
1848 | words, not abbreviations. Keywords and text are in the ISO 8859-1 | |
1849 | (Latin-1) character set (a superset of regular ASCII) and can not | |
1850 | contain NUL characters, and should not contain control or other | |
1851 | unprintable characters. To make the comments widely readable, stick | |
1852 | with basic ASCII, and avoid machine specific character set extensions | |
1853 | like the IBM-PC character set. The keyword must be present, but | |
1854 | you can leave off the text string on non-compressed pairs. | |
1855 | Compressed pairs must have a text string, as only the text string | |
1856 | is compressed anyway, so the compression would be meaningless. | |
1857 | ||
1858 | PNG supports modification time via the png_time structure. Two | |
1859 | conversion routines are proved, png_convert_from_time_t() for | |
1860 | time_t and png_convert_from_struct_tm() for struct tm. The | |
1861 | time_t routine uses gmtime(). You don't have to use either of | |
1862 | these, but if you wish to fill in the png_time structure directly, | |
1863 | you should provide the time in universal time (GMT) if possible | |
1864 | instead of your local time. Note that the year number is the full | |
1865 | year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and | |
1866 | that months start with 1. | |
1867 | ||
1868 | If you want to store the time of the original image creation, you should | |
1869 | use a plain tEXt chunk with the "Creation Time" keyword. This is | |
1870 | necessary because the "creation time" of a PNG image is somewhat vague, | |
1871 | depending on whether you mean the PNG file, the time the image was | |
1872 | created in a non-PNG format, a still photo from which the image was | |
1873 | scanned, or possibly the subject matter itself. In order to facilitate | |
1874 | machine-readable dates, it is recommended that the "Creation Time" | |
a626cc03 | 1875 | tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"), |
c801d85f KB |
1876 | although this isn't a requirement. Unlike the tIME chunk, the |
1877 | "Creation Time" tEXt chunk is not expected to be automatically changed | |
1878 | by the software. To facilitate the use of RFC 1123 dates, a function | |
1879 | png_convert_to_rfc1123(png_timep) is provided to convert from PNG | |
1880 | time to an RFC 1123 format string. | |
1881 | ||
1882 | You are now ready to write all the file information up to the actual | |
1883 | image data. You do this with a call to png_write_info(). | |
1884 | ||
1885 | png_write_info(png_ptr, info_ptr); | |
1886 | ||
1887 | After you've written the file information, you can set up the library | |
1888 | to handle any special transformations of the image data. The various | |
1889 | ways to transform the data will be described in the order that they | |
1890 | should occur. This is important, as some of these change the color | |
1891 | type and/or bit depth of the data, and some others only work on | |
1892 | certain color types and bit depths. Even though each transformation | |
1893 | checks to see if it has data that it can do something with, you should | |
1894 | make sure to only enable a transformation if it will be valid for the | |
1895 | data. For example, don't swap red and blue on grayscale data. | |
1896 | ||
a626cc03 RR |
1897 | PNG files store RGB pixels packed into 3 or 6 bytes. This code tells |
1898 | the library to expand the input data to 4 or 8 bytes per pixel | |
1899 | (or expand 1 or 2-byte grayscale data to 2 or 4 bytes per pixel). | |
c801d85f KB |
1900 | |
1901 | png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE); | |
1902 | ||
1903 | where the 0 is the value that will be put in the 4th byte, and the | |
1904 | location is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending | |
1905 | upon whether the filler byte is stored XRGB or RGBX. | |
1906 | ||
1907 | PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as | |
1908 | they can, resulting in, for example, 8 pixels per byte for 1 bit files. | |
1909 | If the data is supplied at 1 pixel per byte, use this code, which will | |
1910 | correctly pack the pixels into a single byte: | |
1911 | ||
1912 | png_set_packing(png_ptr); | |
1913 | ||
1914 | PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your | |
1915 | data is of another bit depth, you can write an sBIT chunk into the | |
1916 | file so that decoders can get the original data if desired. | |
a626cc03 | 1917 | |
c801d85f KB |
1918 | /* Set the true bit depth of the image data */ |
1919 | if (color_type & PNG_COLOR_MASK_COLOR) | |
1920 | { | |
1921 | sig_bit.red = true_bit_depth; | |
1922 | sig_bit.green = true_bit_depth; | |
1923 | sig_bit.blue = true_bit_depth; | |
1924 | } | |
1925 | else | |
1926 | { | |
1927 | sig_bit.gray = true_bit_depth; | |
1928 | } | |
1929 | if (color_type & PNG_COLOR_MASK_ALPHA) | |
1930 | { | |
1931 | sig_bit.alpha = true_bit_depth; | |
1932 | } | |
1933 | ||
1934 | png_set_sBIT(png_ptr, info_ptr, &sig_bit); | |
1935 | ||
1936 | If the data is stored in the row buffer in a bit depth other than | |
1937 | one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG), | |
1938 | this will scale the values to appear to be the correct bit depth as | |
1939 | is required by PNG. | |
1940 | ||
1941 | png_set_shift(png_ptr, &sig_bit); | |
1942 | ||
1943 | PNG files store 16 bit pixels in network byte order (big-endian, | |
1944 | ie. most significant bits first). This code would be used if they are | |
1945 | supplied the other way (little-endian, i.e. least significant bits | |
1946 | first, the way PCs store them): | |
1947 | ||
1948 | if (bit_depth > 8) | |
1949 | png_set_swap(png_ptr); | |
1950 | ||
1951 | If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you | |
1952 | need to change the order the pixels are packed into bytes, you can use: | |
1953 | ||
1954 | if (bit_depth < 8) | |
1955 | png_set_packswap(png_ptr); | |
1956 | ||
1957 | PNG files store 3 color pixels in red, green, blue order. This code | |
1958 | would be used if they are supplied as blue, green, red: | |
1959 | ||
1960 | png_set_bgr(png_ptr); | |
1961 | ||
1962 | PNG files describe monochrome as black being zero and white being | |
1963 | one. This code would be used if the pixels are supplied with this reversed | |
1964 | (black being one and white being zero): | |
1965 | ||
1966 | png_set_invert_mono(png_ptr); | |
1967 | ||
1968 | Finally, you can write your own transformation function if none of | |
1969 | the existing ones meets your needs. This is done by setting a callback | |
1970 | with | |
1971 | ||
1972 | png_set_write_user_transform_fn(png_ptr, | |
1973 | write_transform_fn); | |
1974 | ||
1975 | You must supply the function | |
1976 | ||
1977 | void write_transform_fn(png_ptr ptr, row_info_ptr | |
a626cc03 | 1978 | row_info, png_bytep data) |
c801d85f KB |
1979 | |
1980 | See pngtest.c for a working example. Your function will be called | |
1981 | before any of the other transformations have been processed. | |
1982 | ||
1983 | It is possible to have libpng flush any pending output, either manually, | |
1984 | or automatically after a certain number of lines have been written. To | |
1985 | flush the output stream a single time call: | |
1986 | ||
1987 | png_write_flush(png_ptr); | |
1988 | ||
1989 | and to have libpng flush the output stream periodically after a certain | |
1990 | number of scanlines have been written, call: | |
1991 | ||
1992 | png_set_flush(png_ptr, nrows); | |
1993 | ||
1994 | Note that the distance between rows is from the last time png_write_flush() | |
1995 | was called, or the first row of the image if it has never been called. | |
1996 | So if you write 50 lines, and then png_set_flush 25, it will flush the | |
1997 | output on the next scanline, and every 25 lines thereafter, unless | |
1998 | png_write_flush() is called before 25 more lines have been written. | |
1999 | If nrows is too small (less than about 10 lines for a 640 pixel wide | |
2000 | RGB image) the image compression may decrease noticeably (although this | |
2001 | may be acceptable for real-time applications). Infrequent flushing will | |
2002 | only degrade the compression performance by a few percent over images | |
2003 | that do not use flushing. | |
2004 | ||
2005 | That's it for the transformations. Now you can write the image data. | |
2006 | The simplest way to do this is in one function call. If have the | |
2007 | whole image in memory, you can just call png_write_image() and libpng | |
2008 | will write the image. You will need to pass in an array of pointers to | |
2009 | each row. This function automatically handles interlacing, so you don't | |
2010 | need to call png_set_interlace_handling() or call this function multiple | |
2011 | times, or any of that other stuff necessary with png_write_rows(). | |
2012 | ||
2013 | png_write_image(png_ptr, row_pointers); | |
2014 | ||
2015 | where row_pointers is: | |
2016 | ||
a626cc03 | 2017 | png_byte *row_pointers[height]; |
c801d85f KB |
2018 | |
2019 | You can point to void or char or whatever you use for pixels. | |
2020 | ||
a626cc03 | 2021 | If you don't want to write the whole image at once, you can |
c801d85f KB |
2022 | use png_write_rows() instead. If the file is not interlaced, |
2023 | this is simple: | |
2024 | ||
2025 | png_write_rows(png_ptr, row_pointers, | |
2026 | number_of_rows); | |
2027 | ||
2028 | row_pointers is the same as in the png_write_image() call. | |
2029 | ||
2030 | If you are just writing one row at a time, you can do this with | |
2031 | row_pointers: | |
2032 | ||
2033 | png_bytep row_pointer = row; | |
2034 | ||
2035 | png_write_row(png_ptr, &row_pointer); | |
2036 | ||
2037 | When the file is interlaced, things can get a good deal more | |
2038 | complicated. The only currently (as of February 1998 -- PNG Specification | |
2039 | version 1.0, dated October 1996) defined interlacing scheme for PNG files | |
2040 | is the "Adam7" interlace scheme, that breaks down an | |
2041 | image into seven smaller images of varying size. libpng will build | |
2042 | these images for you, or you can do them yourself. If you want to | |
2043 | build them yourself, see the PNG specification for details of which | |
2044 | pixels to write when. | |
2045 | ||
2046 | If you don't want libpng to handle the interlacing details, just | |
2047 | use png_set_interlace_handling() and call png_write_rows() the | |
2048 | correct number of times to write all seven sub-images. | |
2049 | ||
2050 | If you want libpng to build the sub-images, call this before you start | |
2051 | writing any rows: | |
2052 | ||
2053 | number_of_passes = | |
2054 | png_set_interlace_handling(png_ptr); | |
2055 | ||
2056 | This will return the number of passes needed. Currently, this | |
2057 | is seven, but may change if another interlace type is added. | |
2058 | ||
2059 | Then write the complete image number_of_passes times. | |
2060 | ||
2061 | png_write_rows(png_ptr, row_pointers, | |
2062 | number_of_rows); | |
2063 | ||
2064 | As some of these rows are not used, and thus return immediately, | |
2065 | you may want to read about interlacing in the PNG specification, | |
2066 | and only update the rows that are actually used. | |
2067 | ||
2068 | After you are finished writing the image, you should finish writing | |
2069 | the file. If you are interested in writing comments or time, you should | |
2070 | pass an appropriately filled png_info pointer. If you are not interested, | |
2071 | you can pass NULL. | |
2072 | ||
2073 | png_write_end(png_ptr, info_ptr); | |
2074 | ||
2075 | When you are done, you can free all memory used by libpng like this: | |
2076 | ||
2077 | png_destroy_write_struct(&png_ptr, &info_ptr); | |
2078 | ||
2079 | You must free any data you allocated for info_ptr, such as comments, | |
2080 | palette, or histogram, before the call to png_destroy_write_struct(); | |
2081 | ||
2082 | For a more compact example of writing a PNG image, see the file example.c. | |
2083 | ||
2084 | ||
2085 | .SH V. Modifying/Customizing libpng: | |
2086 | ||
2087 | There are two issues here. The first is changing how libpng does | |
2088 | standard things like memory allocation, input/output, and error handling. | |
2089 | The second deals with more complicated things like adding new chunks, | |
2090 | adding new transformations, and generally changing how libpng works. | |
2091 | ||
2092 | All of the memory allocation, input/output, and error handling in libpng | |
a626cc03 | 2093 | goes through callbacks that are user settable. The default routines are |
c801d85f KB |
2094 | in pngmem.c, pngrio.c, pngwio.c, and pngerror.c respectively. To change |
2095 | these functions, call the appropriate png_set_???_fn() function. | |
2096 | ||
2097 | Memory allocation is done through the functions png_large_malloc(), | |
2098 | png_malloc(), png_realloc(), png_large_free(), and png_free(). These | |
2099 | currently just call the standard C functions. The large functions must | |
2100 | handle exactly 64K, but they don't have to handle more than that. If | |
2101 | your pointers can't access more then 64K at a time, you will want to set | |
2102 | MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling | |
2103 | memory allocation on a platform will change between applications, these | |
2104 | functions must be modified in the library at compile time. | |
2105 | ||
2106 | Input/Output in libpng is done through png_read() and png_write(), | |
2107 | which currently just call fread() and fwrite(). The FILE * is stored in | |
2108 | png_struct and is initialized via png_init_io(). If you wish to change | |
2109 | the method of I/O, the library supplies callbacks that you can set | |
2110 | through the function png_set_read_fn() and png_set_write_fn() at run | |
2111 | time, instead of calling the png_init_io() function. These functions | |
2112 | also provide a void pointer that can be retrieved via the function | |
2113 | png_get_io_ptr(). For example: | |
2114 | ||
a626cc03 RR |
2115 | png_set_read_fn(png_structp read_ptr, |
2116 | voidp read_io_ptr, png_rw_ptr read_data_fn) | |
c801d85f | 2117 | |
a626cc03 RR |
2118 | png_set_write_fn(png_structp write_ptr, |
2119 | voidp write_io_ptr, png_rw_ptr write_data_fn, | |
c801d85f KB |
2120 | png_flush_ptr output_flush_fn); |
2121 | ||
a626cc03 RR |
2122 | voidp read_io_ptr = png_get_io_ptr(read_ptr); |
2123 | voidp write_io_ptr = png_get_io_ptr(write_ptr); | |
c801d85f KB |
2124 | |
2125 | The replacement I/O functions should have prototypes as follows: | |
2126 | ||
2127 | void user_read_data(png_structp png_ptr, | |
2128 | png_bytep data, png_uint_32 length); | |
2129 | void user_write_data(png_structp png_ptr, | |
2130 | png_bytep data, png_uint_32 length); | |
2131 | void user_flush_data(png_structp png_ptr); | |
2132 | ||
2133 | Supplying NULL for the read, write, or flush functions sets them back | |
2134 | to using the default C stream functions. It is an error to read from | |
2135 | a write stream, and vice versa. | |
2136 | ||
2137 | Error handling in libpng is done through png_error() and png_warning(). | |
2138 | Errors handled through png_error() are fatal, meaning that png_error() | |
2139 | should never return to its caller. Currently, this is handled via | |
2140 | setjmp() and longjmp(), but you could change this to do things like | |
2141 | exit() if you should wish. On non-fatal errors, png_warning() is called | |
2142 | to print a warning message, and then control returns to the calling code. | |
2143 | By default png_error() and png_warning() print a message on stderr via | |
2144 | fprintf() unless the library is compiled with PNG_NO_STDIO defined. If | |
2145 | you wish to change the behavior of the error functions, you will need to | |
2146 | set up your own message callbacks. These functions are normally supplied | |
2147 | at the time that the png_struct is created. It is also possible to change | |
2148 | these functions after png_create_???_struct() has been called by calling: | |
2149 | ||
2150 | png_set_error_fn(png_structp png_ptr, | |
2151 | png_voidp error_ptr, png_error_ptr error_fn, | |
2152 | png_error_ptr warning_fn); | |
2153 | ||
2154 | png_voidp error_ptr = png_get_error_ptr(png_ptr); | |
2155 | ||
2156 | If NULL is supplied for either error_fn or warning_fn, then the libpng | |
2157 | default function will be used, calling fprintf() and/or longjmp() if a | |
2158 | problem is encountered. The replacement error functions should have | |
2159 | parameters as follows: | |
2160 | ||
2161 | void user_error_fn(png_structp png_ptr, | |
2162 | png_const_charp error_msg); | |
2163 | void user_warning_fn(png_structp png_ptr, | |
2164 | png_const_charp warning_msg); | |
2165 | ||
2166 | The motivation behind using setjmp() and longjmp() is the C++ throw and | |
2167 | catch exception handling methods. This makes the code much easier to write, | |
2168 | as there is no need to check every return code of every function call. | |
2169 | However, there are some uncertainties about the status of local variables | |
2170 | after a longjmp, so the user may want to be careful about doing anything after | |
2171 | setjmp returns non-zero besides returning itself. Consult your compiler | |
2172 | documentation for more details. | |
2173 | ||
2174 | If you need to read or write custom chunks, you will need to get deeper | |
2175 | into the libpng code, as a mechanism has not yet been supplied for user | |
2176 | callbacks with custom chunks. First, read the PNG specification, and have | |
2177 | a first level of understanding of how it works. Pay particular attention | |
2178 | to the sections that describe chunk names, and look at how other chunks | |
2179 | were designed, so you can do things similarly. Second, check out the | |
2180 | sections of libpng that read and write chunks. Try to find a chunk that | |
2181 | is similar to yours and copy off of it. More details can be found in the | |
2182 | comments inside the code. A way of handling unknown chunks in a generic | |
2183 | method, potentially via callback functions, would be best. | |
2184 | ||
2185 | If you wish to write your own transformation for the data, look through | |
2186 | the part of the code that does the transformations, and check out some of | |
2187 | the simpler ones to get an idea of how they work. Try to find a similar | |
2188 | transformation to the one you want to add and copy off of it. More details | |
2189 | can be found in the comments inside the code itself. | |
2190 | ||
2191 | Configuring for 16 bit platforms: | |
2192 | ||
2193 | You may need to change the png_large_malloc() and png_large_free() | |
2194 | routines in pngmem.c, as these are required to allocate 64K, although | |
2195 | there is already support for many of the common DOS compilers. Also, | |
2196 | you will want to look into zconf.h to tell zlib (and thus libpng) that | |
2197 | it cannot allocate more then 64K at a time. Even if you can, the memory | |
2198 | won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K. | |
2199 | ||
2200 | Configuring for DOS: | |
2201 | ||
a626cc03 | 2202 | For DOS users who only have access to the lower 640K, you will |
c801d85f KB |
2203 | have to limit zlib's memory usage via a png_set_compression_mem_level() |
2204 | call. See zlib.h or zconf.h in the zlib library for more information. | |
2205 | ||
2206 | Configuring for Medium Model: | |
2207 | ||
2208 | Libpng's support for medium model has been tested on most of the popular | |
2209 | compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets | |
2210 | defined, and FAR gets defined to far in pngconf.h, and you should be | |
2211 | all set. Everything in the library (except for zlib's structure) is | |
2212 | expecting far data. You must use the typedefs with the p or pp on | |
2213 | the end for pointers (or at least look at them and be careful). Make | |
a626cc03 | 2214 | note that the row's of data are defined as png_bytepp, which is an |
c801d85f KB |
2215 | unsigned char far * far *. |
2216 | ||
2217 | Configuring for gui/windowing platforms: | |
2218 | ||
2219 | You will need to write new error and warning functions that use the GUI | |
2220 | interface, as described previously, and set them to be the error and | |
2221 | warning functions at the time that png_create_???_struct() is called, | |
2222 | in order to have them available during the structure initialization. | |
2223 | They can be changed later via png_set_error_fn(). On some compilers, | |
2224 | you may also have to change the memory allocators (png_malloc, etc.). | |
2225 | ||
2226 | Configuring for compiler xxx: | |
2227 | ||
2228 | All includes for libpng are in pngconf.h. If you need to add/change/delete | |
2229 | an include, this is the place to do it. The includes that are not | |
2230 | needed outside libpng are protected by the PNG_INTERNAL definition, | |
2231 | which is only defined for those routines inside libpng itself. The | |
2232 | files in libpng proper only include png.h, which includes pngconf.h. | |
2233 | ||
2234 | Configuring zlib: | |
2235 | ||
2236 | There are special functions to configure the compression. Perhaps the | |
2237 | most useful one changes the compression level, which currently uses | |
2238 | input compression values in the range 0 - 9. The library normally | |
2239 | uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests | |
2240 | have shown that for a large majority of images, compression values in | |
2241 | the range 3-6 compress nearly as well as higher levels, and do so much | |
2242 | faster. For online applications it may be desirable to have maximum speed | |
2243 | (Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also | |
2244 | specify no compression (Z_NO_COMPRESSION = 0), but this would create | |
2245 | files larger than just storing the raw bitmap. You can specify the | |
2246 | compression level by calling: | |
2247 | ||
2248 | png_set_compression_level(png_ptr, level); | |
2249 | ||
2250 | Another useful one is to reduce the memory level used by the library. | |
2251 | The memory level defaults to 8, but it can be lowered if you are | |
2252 | short on memory (running DOS, for example, where you only have 640K). | |
2253 | ||
2254 | png_set_compression_mem_level(png_ptr, level); | |
2255 | ||
2256 | The other functions are for configuring zlib. They are not recommended | |
2257 | for normal use and may result in writing an invalid PNG file. See | |
2258 | zlib.h for more information on what these mean. | |
2259 | ||
2260 | png_set_compression_strategy(png_ptr, | |
2261 | strategy); | |
2262 | png_set_compression_window_bits(png_ptr, | |
2263 | window_bits); | |
2264 | png_set_compression_method(png_ptr, method); | |
2265 | ||
2266 | Controlling row filtering: | |
2267 | ||
2268 | If you want to control whether libpng uses filtering or not, which | |
2269 | filters are used, and how it goes about picking row filters, you | |
2270 | can call one of these functions. The selection and configuration | |
2271 | of row filters can have a significant impact on the size and | |
2272 | encoding speed and a somewhat lesser impact on the decoding speed | |
2273 | of an image. Filtering is enabled by default for RGB and grayscale | |
a626cc03 RR |
2274 | images (with and without alpha), but not for paletted images nor |
2275 | for any images with bit depths less than 8 bits/pixel. | |
c801d85f KB |
2276 | |
2277 | The 'method' parameter sets the main filtering method, which is | |
2278 | currently only '0' in the PNG 1.0 specification. The 'filters' | |
2279 | parameter sets which filter(s), if any, should be used for each | |
2280 | scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS | |
2281 | to turn filtering on and off, respectively. | |
2282 | ||
2283 | Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, | |
2284 | PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise | |
2285 | ORed together '|' to specify one or more filters to use. These | |
2286 | filters are described in more detail in the PNG specification. If | |
2287 | you intend to change the filter type during the course of writing | |
2288 | the image, you should start with flags set for all of the filters | |
2289 | you intend to use so that libpng can initialize its internal | |
2290 | structures appropriately for all of the filter types. | |
2291 | ||
2292 | filters = PNG_FILTER_NONE | PNG_FILTER_SUB | |
2293 | | PNG_FILTER_UP; | |
2294 | png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE, | |
2295 | filters); | |
2296 | ||
2297 | It is also possible to influence how libpng chooses from among the | |
2298 | available filters. This is done in two ways - by telling it how | |
2299 | important it is to keep the same filter for successive rows, and | |
2300 | by telling it the relative computational costs of the filters. | |
2301 | ||
2302 | double weights[3] = {1.5, 1.3, 1.1}, | |
2303 | costs[PNG_FILTER_VALUE_LAST] = | |
2304 | {1.0, 1.3, 1.3, 1.5, 1.7}; | |
2305 | ||
2306 | png_set_filter_selection(png_ptr, | |
2307 | PNG_FILTER_SELECTION_WEIGHTED, 3, | |
2308 | weights, costs); | |
2309 | ||
a626cc03 RR |
2310 | The weights are multiplying factors that indicate to libpng that the |
2311 | row filter should be the same for successive rows unless another row filter | |
2312 | is that many times better than the previous filter. In the above example, | |
2313 | if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a | |
c801d85f KB |
2314 | "sum of absolute differences" 1.5 x 1.3 times higher than other filters |
2315 | and still be chosen, while the NONE filter could have a sum 1.1 times | |
2316 | higher than other filters and still be chosen. Unspecified weights are | |
2317 | taken to be 1.0, and the specified weights should probably be declining | |
2318 | like those above in order to emphasize recent filters over older filters. | |
2319 | ||
2320 | The filter costs specify for each filter type a relative decoding cost | |
2321 | to be considered when selecting row filters. This means that filters | |
2322 | with higher costs are less likely to be chosen over filters with lower | |
2323 | costs, unless their "sum of absolute differences" is that much smaller. | |
2324 | The costs do not necessarily reflect the exact computational speeds of | |
2325 | the various filters, since this would unduly influence the final image | |
2326 | size. | |
2327 | ||
2328 | Note that the numbers above were invented purely for this example and | |
2329 | are given only to help explain the function usage. Little testing has | |
2330 | been done to find optimum values for either the costs or the weights. | |
2331 | ||
2332 | Removing unwanted object code: | |
2333 | ||
2334 | There are a bunch of #define's in pngconf.h that control what parts of | |
2335 | libpng are compiled. All the defines end in _SUPPORTED. If you are | |
a626cc03 RR |
2336 | never going to use a capability, you can change the #define to #undef |
2337 | before recompiling libpng and save yourself code and data space, or | |
2338 | you can turn off individual capabilities with defines that begin with | |
2339 | PNG_NO_. | |
2340 | ||
2341 | You can also turn all of the transforms and ancillary chunk capabilities | |
2342 | off en masse with compiler directives that define | |
2343 | PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, | |
2344 | or all four, | |
c801d85f | 2345 | along with directives to turn on any of the capabilities that you do |
a626cc03 | 2346 | want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable |
c801d85f KB |
2347 | the extra transformations but still leave the library fully capable of reading |
2348 | and writing PNG files with all known public chunks [except for sPLT]. | |
a626cc03 | 2349 | Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive |
c801d85f KB |
2350 | produces a library that is incapable of reading or writing ancillary chunks. |
2351 | If you are not using the progressive reading capability, you can | |
a626cc03 | 2352 | turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse |
c801d85f KB |
2353 | this with the INTERLACING capability, which you'll still have). |
2354 | ||
2355 | All the reading and writing specific code are in separate files, so the | |
2356 | linker should only grab the files it needs. However, if you want to | |
2357 | make sure, or if you are building a stand alone library, all the | |
2358 | reading files start with pngr and all the writing files start with | |
2359 | pngw. The files that don't match either (like png.c, pngtrans.c, etc.) | |
2360 | are used for both reading and writing, and always need to be included. | |
2361 | The progressive reader is in pngpread.c | |
2362 | ||
2363 | If you are creating or distributing a dynamically linked library (a .so | |
2364 | or DLL file), you should not remove or disable any parts of the library, | |
2365 | as this will cause applications linked with different versions of the | |
2366 | library to fail if they call functions not available in your library. | |
2367 | The size of the library itself should not be an issue, because only | |
a626cc03 RR |
2368 | those sections that are actually used will be loaded into memory. |
2369 | ||
2370 | Requesting debug printout: | |
2371 | ||
2372 | The macro definition PNG_DEBUG can be used to request debugging | |
2373 | printout. Set it to an integer value in the range 0 to 3. Higher | |
2374 | numbers result in increasing amounts of debugging information. The | |
2375 | information is printed to the "stderr" file, unless another file | |
2376 | name is specified in the PNG_DEBUG_FILE macro definition. | |
2377 | ||
2378 | When PNG_DEBUG > 0, the following functions (macros) become available: | |
2379 | ||
2380 | png_debug(level, message) | |
2381 | png_debug1(level, message, p1) | |
2382 | png_debug2(level, message, p1, p2) | |
2383 | ||
2384 | in which "level" is compared to PNG_DEBUG to decide whether to print | |
2385 | the message, "message" is the formatted string to be printed, | |
2386 | and p1 and p2 are parameters that are to be embedded in the string | |
2387 | according to printf-style formatting directives. For example, | |
2388 | ||
2389 | png_debug1(2, "foo=%d\n", foo); | |
c801d85f | 2390 | |
a626cc03 | 2391 | is expanded to |
c801d85f | 2392 | |
a626cc03 RR |
2393 | if(PNG_DEBUG > 2) |
2394 | fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo); | |
2395 | ||
2396 | When PNG_DEBUG is defined but is zero, the macros aren't defined, but you | |
2397 | can still use PNG_DEBUG to control your own debugging: | |
2398 | ||
2399 | #ifdef PNG_DEBUG | |
2400 | fprintf(stderr, ... | |
2401 | #endif | |
2402 | ||
2403 | When PNG_DEBUG = 1, the macros are defined, but only png_debug statements | |
2404 | having level = 0 will be printed. There aren't any such statements in | |
2405 | this version of libpng, but if you insert some they will be printed. | |
2406 | ||
2407 | .SH VI. Changes to Libpng from version 0.88 | |
c801d85f KB |
2408 | |
2409 | It should be noted that versions of libpng later than 0.96 are not | |
2410 | distributed by the original libpng author, Guy Schalnat, nor by | |
2411 | Andreas Dilger, who had taken over from Guy during 1996 and 1997, and | |
2412 | distributed versions 0.89 through 0.96, but rather by another member | |
2413 | of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are | |
2414 | still alive and well, but they have moved on to other things. | |
2415 | ||
2416 | The old libpng functions png_read_init(), png_write_init(), | |
2417 | png_info_init(), png_read_destroy(), and png_write_destory() have been | |
2418 | moved to PNG_INTERNAL in version 0.95 to discourage their use. The | |
2419 | preferred method of creating and initializing the libpng structures is | |
2420 | via the png_create_read_struct(), png_create_write_struct(), and | |
2421 | png_create_info_struct() because they isolate the size of the structures | |
2422 | from the application, allow version error checking, and also allow the | |
2423 | use of custom error handling routines during the initialization, which | |
2424 | the old functions do not. The functions png_read_destroy() and | |
2425 | png_write_destroy() do not actually free the memory that libpng | |
2426 | allocated for these structs, but just reset the data structures, so they | |
2427 | can be used instead of png_destroy_read_struct() and | |
2428 | png_destroy_write_struct() if you feel there is too much system overhead | |
2429 | allocating and freeing the png_struct for each image read. | |
2430 | ||
2431 | Setting the error callbacks via png_set_message_fn() before | |
2432 | png_read_init() as was suggested in libpng-0.88 is no longer supported | |
a626cc03 | 2433 | because this caused applications that do not use custom error functions |
c801d85f KB |
2434 | to fail if the png_ptr was not initialized to zero. It is still possible |
2435 | to set the error callbacks AFTER png_read_init(), or to change them with | |
2436 | png_set_error_fn(), which is essentially the same function, but with a | |
2437 | new name to force compilation errors with applications that try to use | |
2438 | the old method. | |
2439 | ||
a626cc03 RR |
2440 | .SH VII. Y2K Compliance in libpng |
2441 | ||
2442 | January 13, 1999 | |
2443 | ||
2444 | Since the PNG Development group is an ad-hoc body, we can't make | |
2445 | an official declaration. | |
2446 | ||
2447 | This is your unofficial assurance that libpng from version 0.81 and | |
2448 | upward are Y2K compliant. It is my belief that earlier versions were | |
2449 | also Y2K compliant. | |
2450 | ||
2451 | Libpng only has three year fields. One is a 2-byte unsigned integer that | |
2452 | will hold years up to 65535. The other two hold the date in text | |
2453 | format, and will hold years up to 9999. | |
2454 | ||
2455 | The integer is | |
2456 | "png_uint_16 year" in png_time_struct. | |
2457 | ||
2458 | The strings are | |
2459 | "png_charp time_buffer" in png_struct and | |
2460 | "near_time_buffer", which is a local character string in png.c. | |
2461 | ||
2462 | There are seven time-related functions: | |
2463 | ||
2464 | png_convert_to_rfc_1123() in png.c | |
2465 | (formerly png_convert_to_rfc_1152() in error) | |
2466 | png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c | |
2467 | png_convert_from_time_t() in pngwrite.c | |
2468 | png_get_tIME() in pngget.c | |
2469 | png_handle_tIME() in pngrutil.c, called in pngread.c | |
2470 | png_set_tIME() in pngset.c | |
2471 | png_write_tIME() in pngwutil.c, called in pngwrite.c | |
2472 | ||
2473 | All appear to handle dates properly in a Y2K environment. The | |
2474 | png_convert_from_time_t() function calls gmtime() to convert from system | |
2475 | clock time, which returns (year - 1900), which we properly convert to | |
2476 | the full 4-digit year. There is a possibility that applications using | |
2477 | libpng are not passing 4-digit years into the png_convert_to_rfc_1123() | |
2478 | function, or incorrectly passing only a 2-digit year instead of | |
2479 | "year - 1900" into the png_convert_from_struct_tm() function, but this | |
2480 | is not under our control. The libpng documentation has always stated | |
2481 | that it works with 4-digit years, and the APIs have been documented as | |
2482 | such. | |
2483 | ||
2484 | The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned | |
2485 | integer to hold the year, and can hold years as large as 65535. | |
2486 | ||
2487 | ||
2488 | Glenn Randers-Pehrson | |
2489 | libpng maintainer | |
2490 | PNG Development Group | |
2491 | ||
c801d85f KB |
2492 | .SH NOTE |
2493 | ||
2494 | Note about libpng version numbers: | |
2495 | ||
2496 | Due to various miscommunications, unforeseen code incompatibilities | |
2497 | and occasional factors outside the authors' control, version numbering | |
2498 | on the library has not always been consistent and straightforward. | |
2499 | The following table summarizes matters since version 0.89c, which was | |
2500 | the first widely used release: | |
2501 | ||
2502 | source png.h png.h shared-lib | |
2503 | version string int version | |
2504 | ------- ------ ------ ---------- | |
2505 | 0.89c 0.89 89 1.0.89 | |
2506 | 0.90 0.90 90 0.90 [should be 2.0.90] | |
2507 | 0.95 0.95 95 0.95 [should be 2.0.95] | |
2508 | 0.96 0.96 96 0.96 [should be 2.0.96] | |
2509 | 0.97b 1.00.97 97 1.0.1 [should be 2.0.97] | |
2510 | 0.97c 0.97 97 2.0.97 | |
2511 | 0.98 0.98 98 2.0.98 | |
2512 | 0.99 0.99 98 2.0.99 | |
2513 | 0.99a-m 0.99 99 2.0.99 | |
2514 | 1.00 1.00 100 2.1.0 [int should be 10000] | |
2515 | 1.0.0 1.0.0 100 2.1.0 [int should be 10000] | |
2516 | 1.0.1 1.0.1 10001 2.1.0 | |
2517 | ||
2518 | Henceforth the source version will match the shared-library | |
2519 | minor and patch numbers; the shared-library major version number will be | |
2520 | used for changes in backward compatibility, as it is intended. | |
2521 | The PNG_PNGLIB_VER macro, which is not used within libpng but | |
2522 | is available for applications, is an unsigned integer of the form | |
2523 | xyyzz corresponding to the source version x.y.z (leading zeros in y and z). | |
2524 | ||
2525 | .SH "SEE ALSO" | |
2526 | libpngpf(3), png(5) | |
2527 | .LP | |
2528 | .IR libpng : | |
2529 | .IP | |
2530 | ftp://ftp.uu.net/graphics/png | |
2531 | http://www.cdrom.com/pub/png | |
2532 | ||
2533 | .LP | |
2534 | .IR zlib : | |
2535 | .IP | |
2536 | (generally) at the same location as | |
2537 | .I libpng | |
2538 | or at | |
2539 | .br | |
2540 | ftp://ftp.uu.net/pub/archiving/zip/zlib | |
2541 | .br | |
2542 | http://www.cdrom.com/pub/infozip/zlib | |
2543 | ||
2544 | .LP | |
2545 | .IR PNG specification: RFC 2083 | |
2546 | .IP | |
2547 | (generally) at the same location as | |
2548 | .I libpng | |
2549 | or at | |
2550 | .br | |
2551 | ftp://ds.internic.net/rfc/rfc2083.txt | |
2552 | .br | |
2553 | or (as a W3C Recommendation) at | |
2554 | .br | |
2555 | http://www.w3.org/TR/REC-png.html | |
2556 | ||
2557 | .LP | |
2558 | In the case of any inconsistency between the PNG specification | |
2559 | and this library, the specification takes precedence. | |
2560 | ||
2561 | .SH AUTHORS | |
2562 | This man page: Glenn Randers-Pehrson | |
2563 | <randeg@alumni.rpi.edu> | |
2564 | ||
2565 | Contributing Authors: John Bowler, Kevin Bracey, Sam Bushell, Andreas Dilger, | |
2566 | Magnus Holmgren, Tom Lane, Dave Martindale, Glenn Randers-Pehrson, | |
2567 | Greg Roelofs, Guy Eric Schalnat, Paul Schmidt, Tom Tanner, Willem van | |
2568 | Schaik, Tim Wegner. | |
2569 | <png-implement@dworkin.wustl.edu> | |
2570 | ||
2571 | The contributing authors would like to thank all those who helped | |
2572 | with testing, bug fixes, and patience. This wouldn't have been | |
2573 | possible without all of you. | |
2574 | ||
2575 | Thanks to Frank J. T. Wojcik for helping with the documentation. | |
2576 | ||
a626cc03 | 2577 | Libpng version 1.0.3 - January 14, 1999: |
c801d85f KB |
2578 | Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. |
2579 | Currently maintained by Glenn Randers-Pehrson (randeg@alumni.rpi.edu). | |
2580 | ||
2581 | Supported by the PNG development group | |
2582 | .br | |
2583 | (png-implement@dworkin.wustl.edu). | |
2584 | ||
2585 | .SH COPYRIGHT NOTICE: | |
2586 | ||
a626cc03 RR |
2587 | Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. |
2588 | Copyright (c) 1996, 1997 Andreas Dilger | |
2589 | Copyright (c) 1998, 1999 Glenn Randers-Pehrson | |
2590 | ||
c801d85f KB |
2591 | The PNG Reference Library (libpng) is supplied "AS IS". The Contributing |
2592 | Authors and Group 42, Inc. disclaim all warranties, expressed or implied, | |
2593 | including, without limitation, the warranties of merchantability and of | |
2594 | fitness for any purpose. The Contributing Authors and Group 42, Inc. | |
2595 | assume no liability for direct, indirect, incidental, special, exemplary, | |
2596 | or consequential damages, which may result from the use of the PNG | |
2597 | Reference Library, even if advised of the possibility of such damage. | |
2598 | ||
2599 | Permission is hereby granted to use, copy, modify, and distribute this | |
2600 | source code, or portions hereof, for any purpose, without fee, subject | |
2601 | to the following restrictions: | |
2602 | ||
2603 | 1. The origin of this source code must not be | |
2604 | misrepresented. | |
2605 | ||
2606 | 2. Altered versions must be plainly marked as such | |
2607 | and must not be misrepresented as being the | |
2608 | original source. | |
2609 | ||
2610 | 3. This Copyright notice may not be removed or | |
2611 | altered from any source or altered source | |
2612 | distribution. | |
2613 | ||
2614 | The Contributing Authors and Group 42, Inc. specifically permit, without | |
2615 | fee, and encourage the use of this source code as a component to | |
2616 | supporting the PNG file format in commercial products. If you use this | |
2617 | source code in a product, acknowledgment is not required but would be | |
2618 | appreciated. | |
2619 | ||
2620 | .\" end of man page | |
2621 |