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