1LIBPNG(3)                  Library Functions Manual                  LIBPNG(3)
2
3
4

NAME

6       libpng - Portable Network Graphics (PNG) Reference Library 1.2.46
7

SYNOPSIS

9
10
11       #include <png.h>
12
13
14
15       png_uint_32 png_access_version_number (void);
16
17
18
19       int png_check_sig (png_bytep sig, int num);
20
21
22
23       void png_chunk_error (png_structp png_ptr, png_const_charp error);
24
25
26
27       void png_chunk_warning (png_structp png_ptr, png_const_charp message);
28
29
30
31       void  png_convert_from_struct_tm  (png_timep  ptime,  struct  tm  FAR *
32       ttime);
33
34
35
36       void png_convert_from_time_t (png_timep ptime, time_t ttime);
37
38
39
40       png_charp  png_convert_to_rfc1123   (png_structp   png_ptr,   png_timep
41       ptime);
42
43
44
45       png_infop png_create_info_struct (png_structp png_ptr);
46
47
48
49       png_structp   png_create_read_struct   (png_const_charp   user_png_ver,
50       png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);
51
52
53
54       png_structp   png_create_read_struct_2(png_const_charp    user_png_ver,
55       png_voidp  error_ptr,  png_error_ptr  error_fn,  png_error_ptr warn_fn,
56       png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);
57
58
59
60       png_structp  png_create_write_struct   (png_const_charp   user_png_ver,
61       png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);
62
63
64
65       png_structp   png_create_write_struct_2(png_const_charp   user_png_ver,
66       png_voidp error_ptr,  png_error_ptr  error_fn,  png_error_ptr  warn_fn,
67       png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);
68
69
70
71       int png_debug(int level, png_const_charp message);
72
73
74
75       int png_debug1(int level, png_const_charp message, p1);
76
77
78
79       int png_debug2(int level, png_const_charp message, p1, p2);
80
81
82
83       void    png_destroy_info_struct    (png_structp   png_ptr,   png_infopp
84       info_ptr_ptr);
85
86
87
88       void  png_destroy_read_struct  (png_structpp  png_ptr_ptr,   png_infopp
89       info_ptr_ptr, png_infopp end_info_ptr_ptr);
90
91
92
93       void  png_destroy_write_struct  (png_structpp  png_ptr_ptr,  png_infopp
94       info_ptr_ptr);
95
96
97
98       void png_error (png_structp png_ptr, png_const_charp error);
99
100
101
102       void png_free (png_structp png_ptr, png_voidp ptr);
103
104
105
106       void png_free_chunk_list (png_structp png_ptr);
107
108
109
110       void png_free_default(png_structp png_ptr, png_voidp ptr);
111
112
113
114       void png_free_data (png_structp png_ptr, png_infop info_ptr, int num);
115
116
117
118       png_byte png_get_bit_depth (png_structp png_ptr, png_infop info_ptr);
119
120
121
122       png_uint_32  png_get_bKGD  (png_structp  png_ptr,  png_infop  info_ptr,
123       png_color_16p *background);
124
125
126
127       png_byte png_get_channels (png_structp png_ptr, png_infop info_ptr);
128
129
130
131       png_uint_32 png_get_cHRM (png_structp png_ptr, png_infop info_ptr, dou‐
132       ble *white_x, double *white_y, double  *red_x,  double  *red_y,  double
133       *green_x, double *green_y, double *blue_x, double *blue_y);
134
135
136
137       png_uint_32    png_get_cHRM_fixed   (png_structp   png_ptr,   png_infop
138       info_ptr,  png_uint_32  *white_x,  png_uint_32  *white_y,   png_uint_32
139       *red_x, png_uint_32 *red_y, png_uint_32 *green_x, png_uint_32 *green_y,
140       png_uint_32 *blue_x, png_uint_32 *blue_y);
141
142
143
144       png_byte png_get_color_type (png_structp png_ptr, png_infop info_ptr);
145
146
147
148       png_byte  png_get_compression_type  (png_structp   png_ptr,   png_infop
149       info_ptr);
150
151
152
153       png_byte png_get_copyright (png_structp png_ptr);
154
155
156
157       png_voidp png_get_error_ptr (png_structp png_ptr);
158
159
160
161       png_byte png_get_filter_type (png_structp png_ptr, png_infop info_ptr);
162
163
164
165       png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop info_ptr, dou‐
166       ble *file_gamma);
167
168
169
170       png_uint_32   png_get_gAMA_fixed   (png_structp   png_ptr,    png_infop
171       info_ptr, png_uint_32 *int_file_gamma);
172
173
174
175       png_byte png_get_header_ver (png_structp png_ptr);
176
177
178
179       png_byte png_get_header_version (png_structp png_ptr);
180
181
182
183       png_uint_32  png_get_hIST  (png_structp  png_ptr,  png_infop  info_ptr,
184       png_uint_16p *hist);
185
186
187
188       png_uint_32  png_get_iCCP  (png_structp  png_ptr,  png_infop  info_ptr,
189       png_charpp name, int *compression_type, png_charpp profile, png_uint_32
190       *proflen);
191
192
193
194       png_uint_32  png_get_IHDR  (png_structp  png_ptr,  png_infop  info_ptr,
195       png_uint_32   *width,   png_uint_32   *height,   int   *bit_depth,  int
196       *color_type, int  *interlace_type,  int  *compression_type,  int  *fil‐
197       ter_type);
198
199
200
201       png_uint_32   png_get_image_height   (png_structp   png_ptr,  png_infop
202       info_ptr);
203
204
205
206       png_uint_32   png_get_image_width   (png_structp   png_ptr,   png_infop
207       info_ptr);
208
209
210
211       #if !defined(PNG_1_0_X)
212
213       png_int_32 png_get_int_32 (png_bytep buf);
214
215       #endif
216
217
218
219       png_byte   png_get_interlace_type   (png_structp   png_ptr,   png_infop
220       info_ptr);
221
222
223
224       png_voidp png_get_io_ptr (png_structp png_ptr);
225
226
227
228       png_byte png_get_libpng_ver (png_structp png_ptr);
229
230
231
232       png_voidp png_get_mem_ptr(png_structp png_ptr);
233
234
235
236       png_uint_32  png_get_oFFs  (png_structp  png_ptr,  png_infop  info_ptr,
237       png_uint_32 *offset_x, png_uint_32 *offset_y, int *unit_type);
238
239
240
241       png_uint_32  png_get_pCAL  (png_structp  png_ptr,  png_infop  info_ptr,
242       png_charp *purpose, png_int_32 *X0,  png_int_32  *X1,  int  *type,  int
243       *nparams, png_charp *units, png_charpp *params);
244
245
246
247       png_uint_32  png_get_pHYs  (png_structp  png_ptr,  png_infop  info_ptr,
248       png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type);
249
250
251
252       float  png_get_pixel_aspect_ratio   (png_structp   png_ptr,   png_infop
253       info_ptr);
254
255
256
257       png_uint_32  png_get_pixels_per_meter  (png_structp  png_ptr, png_infop
258       info_ptr);
259
260
261
262       png_voidp png_get_progressive_ptr (png_structp png_ptr);
263
264
265
266       png_uint_32  png_get_PLTE  (png_structp  png_ptr,  png_infop  info_ptr,
267       png_colorp *palette, int *num_palette);
268
269
270
271       png_byte png_get_rgb_to_gray_status (png_structp png_ptr)
272
273       png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop info_ptr);
274
275
276
277       png_bytepp png_get_rows (png_structp png_ptr, png_infop info_ptr);
278
279
280
281       png_uint_32  png_get_sBIT  (png_structp  png_ptr,  png_infop  info_ptr,
282       png_color_8p *sig_bit);
283
284
285
286       png_bytep png_get_signature (png_structp png_ptr, png_infop info_ptr);
287
288
289
290       png_uint_32  png_get_sPLT  (png_structp  png_ptr,  png_infop  info_ptr,
291       png_spalette_p *splt_ptr);
292
293
294
295       png_uint_32  png_get_sRGB (png_structp png_ptr, png_infop info_ptr, int
296       *intent);
297
298
299
300       png_uint_32  png_get_text  (png_structp  png_ptr,  png_infop  info_ptr,
301       png_textp *text_ptr, int *num_text);
302
303
304
305       png_uint_32  png_get_tIME  (png_structp  png_ptr,  png_infop  info_ptr,
306       png_timep *mod_time);
307
308
309
310       png_uint_32  png_get_tRNS  (png_structp  png_ptr,  png_infop  info_ptr,
311       png_bytep *trans, int *num_trans, png_color_16p *trans_values);
312
313
314
315       #if !defined(PNG_1_0_X)
316
317       png_uint_16 png_get_uint_16 (png_bytep buf);
318
319
320
321       png_uint_32 png_get_uint_31 (png_bytep buf);
322
323
324
325       png_uint_32 png_get_uint_32 (png_bytep buf);
326
327       #endif
328
329
330
331       png_uint_32   png_get_unknown_chunks  (png_structp  png_ptr,  png_infop
332       info_ptr, png_unknown_chunkpp unknowns);
333
334
335
336       png_voidp png_get_user_chunk_ptr (png_structp png_ptr);
337
338
339
340       png_uint_32 png_get_user_height_max( png_structp png_ptr);
341
342
343
344       png_voidp png_get_user_transform_ptr (png_structp png_ptr);
345
346
347
348       png_uint_32 png_get_user_width_max (png_structp png_ptr);
349
350
351
352       png_uint_32 png_get_valid  (png_structp  png_ptr,  png_infop  info_ptr,
353       png_uint_32 flag);
354
355
356
357       png_int_32  png_get_x_offset_microns  (png_structp  png_ptr,  png_infop
358       info_ptr);
359
360
361
362       png_int_32  png_get_x_offset_pixels  (png_structp  png_ptr,   png_infop
363       info_ptr);
364
365
366
367       png_uint_32  png_get_x_pixels_per_meter (png_structp png_ptr, png_infop
368       info_ptr);
369
370
371
372       png_int_32  png_get_y_offset_microns  (png_structp  png_ptr,  png_infop
373       info_ptr);
374
375
376
377       png_int_32   png_get_y_offset_pixels  (png_structp  png_ptr,  png_infop
378       info_ptr);
379
380
381
382       png_uint_32 png_get_y_pixels_per_meter (png_structp png_ptr,  png_infop
383       info_ptr);
384
385
386
387       png_uint_32 png_get_compression_buffer_size (png_structp png_ptr);
388
389
390
391       int png_handle_as_unknown (png_structp png_ptr, png_bytep chunk_name);
392
393
394
395       void png_init_io (png_structp png_ptr, FILE *fp);
396
397
398
399       DEPRECATED: void png_info_init (png_infop info_ptr);
400
401
402
403       DEPRECATED:   void   png_info_init_2  (png_infopp  ptr_ptr,  png_size_t
404       png_info_struct_size);
405
406
407
408       png_voidp png_malloc (png_structp png_ptr, png_uint_32 size);
409
410
411
412       png_voidp png_malloc_default(png_structp png_ptr, png_uint_32 size);
413
414
415
416       voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size);
417
418
419
420       png_voidp  png_memcpy_check   (png_structp   png_ptr,   png_voidp   s1,
421       png_voidp s2, png_uint_32 size);
422
423
424
425       voidp png_memset (png_voidp s1, int value, png_size_t size);
426
427
428
429       png_voidp  png_memset_check  (png_structp  png_ptr,  png_voidp  s1, int
430       value, png_uint_32 size);
431
432
433
434       DEPRECATED:  void  png_permit_empty_plte  (png_structp   png_ptr,   int
435       empty_plte_permitted);
436
437
438
439       void   png_process_data   (png_structp   png_ptr,  png_infop  info_ptr,
440       png_bytep buffer, png_size_t buffer_size);
441
442
443
444       void  png_progressive_combine_row   (png_structp   png_ptr,   png_bytep
445       old_row, png_bytep new_row);
446
447
448
449       void   png_read_destroy   (png_structp   png_ptr,  png_infop  info_ptr,
450       png_infop end_info_ptr);
451
452
453
454       void png_read_end (png_structp png_ptr, png_infop info_ptr);
455
456
457
458       void png_read_image (png_structp png_ptr, png_bytepp image);
459
460
461
462       DEPRECATED: void png_read_init (png_structp png_ptr);
463
464
465
466       DEPRECATED: void png_read_init_2 (png_structpp ptr_ptr, png_const_charp
467       user_png_ver, png_size_t png_struct_size, png_size_t png_info_size);
468
469
470
471       void png_read_info (png_structp png_ptr, png_infop info_ptr);
472
473
474
475       void  png_read_png (png_structp png_ptr, png_infop info_ptr, int trans‐
476       forms, png_voidp params);
477
478
479
480       void png_read_row (png_structp png_ptr, png_bytep row,  png_bytep  dis‐
481       play_row);
482
483
484
485       void  png_read_rows  (png_structp  png_ptr,  png_bytepp row, png_bytepp
486       display_row, png_uint_32 num_rows);
487
488
489
490       void png_read_update_info (png_structp png_ptr, png_infop info_ptr);
491
492
493
494       #if !defined(PNG_1_0_X)
495
496       png_save_int_32 (png_bytep buf, png_int_32 i);
497
498
499
500       void png_save_uint_16 (png_bytep buf, unsigned int i);
501
502
503
504       void png_save_uint_32 (png_bytep buf, png_uint_32 i);
505
506
507
508       void png_set_add_alpha (png_structp png_ptr,  png_uint_32  filler,  int
509       flags);
510
511       #endif
512
513
514
515       void   png_set_background  (png_structp  png_ptr,  png_color_16p  back‐
516       ground_color, int background_gamma_code, int need_expand, double  back‐
517       ground_gamma);
518
519
520
521       void png_set_bgr (png_structp png_ptr);
522
523
524
525       void    png_set_bKGD    (png_structp   png_ptr,   png_infop   info_ptr,
526       png_color_16p background);
527
528
529
530       void png_set_cHRM  (png_structp  png_ptr,  png_infop  info_ptr,  double
531       white_x,  double  white_y,  double red_x, double red_y, double green_x,
532       double green_y, double blue_x, double blue_y);
533
534
535
536       void  png_set_cHRM_fixed  (png_structp  png_ptr,  png_infop   info_ptr,
537       png_uint_32    white_x,   png_uint_32   white_y,   png_uint_32   red_x,
538       png_uint_32   red_y,   png_uint_32   green_x,   png_uint_32    green_y,
539       png_uint_32 blue_x, png_uint_32 blue_y);
540
541
542
543       void png_set_compression_level (png_structp png_ptr, int level);
544
545
546
547       void    png_set_compression_mem_level    (png_structp    png_ptr,   int
548       mem_level);
549
550
551
552       void png_set_compression_method (png_structp png_ptr, int method);
553
554
555
556       void png_set_compression_strategy (png_structp png_ptr, int strategy);
557
558
559
560       void png_set_compression_window_bits  (png_structp  png_ptr,  int  win‐
561       dow_bits);
562
563
564
565       void  png_set_crc_action  (png_structp  png_ptr,  int  crit_action, int
566       ancil_action);
567
568
569
570       void  png_set_dither  (png_structp  png_ptr,  png_colorp  palette,  int
571       num_palette,    int   maximum_colors,   png_uint_16p   histogram,   int
572       full_dither);
573
574
575
576       void  png_set_error_fn  (png_structp  png_ptr,   png_voidp   error_ptr,
577       png_error_ptr error_fn, png_error_ptr warning_fn);
578
579
580
581       void png_set_expand (png_structp png_ptr);
582
583
584
585       void png_set_expand_gray_1_2_4_to_8(png_structp png_ptr);
586
587
588
589       void  png_set_filler  (png_structp  png_ptr,  png_uint_32  filler,  int
590       flags);
591
592
593
594       void png_set_filter (png_structp png_ptr, int method, int filters);
595
596
597
598       void  png_set_filter_heuristics  (png_structp  png_ptr,   int   heuris‐
599       tic_method,  int  num_weights,  png_doublep filter_weights, png_doublep
600       filter_costs);
601
602
603
604       void png_set_flush (png_structp png_ptr, int nrows);
605
606
607
608       void png_set_gamma (png_structp png_ptr,  double  screen_gamma,  double
609       default_file_gamma);
610
611
612
613       void  png_set_gAMA  (png_structp  png_ptr,  png_infop  info_ptr, double
614       file_gamma);
615
616
617
618       void  png_set_gAMA_fixed  (png_structp  png_ptr,  png_infop   info_ptr,
619       png_uint_32 file_gamma);
620
621
622
623       void png_set_gray_1_2_4_to_8(png_structp png_ptr);
624
625
626
627       void png_set_gray_to_rgb (png_structp png_ptr);
628
629
630
631       void    png_set_hIST    (png_structp   png_ptr,   png_infop   info_ptr,
632       png_uint_16p hist);
633
634
635
636       void png_set_iCCP (png_structp png_ptr, png_infop  info_ptr,  png_charp
637       name, int compression_type, png_charp profile, png_uint_32 proflen);
638
639
640
641       int png_set_interlace_handling (png_structp png_ptr);
642
643
644
645       void  png_set_invalid  (png_structp  png_ptr,  png_infop  info_ptr, int
646       mask);
647
648
649
650       void png_set_invert_alpha (png_structp png_ptr);
651
652
653
654       void png_set_invert_mono (png_structp png_ptr);
655
656
657
658       void png_set_IHDR (png_structp png_ptr, png_infop info_ptr, png_uint_32
659       width,  png_uint_32  height,  int bit_depth, int color_type, int inter‐
660       lace_type, int compression_type, int filter_type);
661
662
663
664       void  png_set_keep_unknown_chunks  (png_structp  png_ptr,   int   keep,
665       png_bytep chunk_list, int num_chunks);
666
667
668
669       void  png_set_mem_fn(png_structp  png_ptr,  png_voidp mem_ptr, png_mal‐
670       loc_ptr malloc_fn, png_free_ptr free_fn);
671
672
673
674       void png_set_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32
675       offset_x, png_uint_32 offset_y, int unit_type);
676
677
678
679       void png_set_packing (png_structp png_ptr);
680
681
682
683       void png_set_packswap (png_structp png_ptr);
684
685
686
687       void png_set_palette_to_rgb(png_structp png_ptr);
688
689
690
691       void  png_set_pCAL  (png_structp png_ptr, png_infop info_ptr, png_charp
692       purpose, png_int_32 X0, png_int_32 X1, int type, int nparams, png_charp
693       units, png_charpp params);
694
695
696
697       void png_set_pHYs (png_structp png_ptr, png_infop info_ptr, png_uint_32
698       res_x, png_uint_32 res_y, int unit_type);
699
700
701
702       void png_set_progressive_read_fn (png_structp png_ptr,  png_voidp  pro‐
703       gressive_ptr, png_progressive_info_ptr info_fn, png_progressive_row_ptr
704       row_fn, png_progressive_end_ptr end_fn);
705
706
707
708       void png_set_PLTE (png_structp png_ptr, png_infop info_ptr,  png_colorp
709       palette, int num_palette);
710
711
712
713       void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr
714       read_data_fn);
715
716
717
718       void png_set_read_status_fn (png_structp  png_ptr,  png_read_status_ptr
719       read_row_fn);
720
721
722
723       void      png_set_read_user_transform_fn      (png_structp     png_ptr,
724       png_user_transform_ptr read_user_transform_fn);
725
726
727
728       void png_set_rgb_to_gray (png_structp png_ptr, int error_action, double
729       red, double green);
730
731
732
733       void  png_set_rgb_to_gray_fixed  (png_structp png_ptr, int error_action
734       png_fixed_point red, png_fixed_point green);
735
736
737
738       void png_set_rows (png_structp png_ptr, png_infop info_ptr,  png_bytepp
739       row_pointers);
740
741
742
743       void    png_set_sBIT    (png_structp   png_ptr,   png_infop   info_ptr,
744       png_color_8p sig_bit);
745
746
747
748       void png_set_sCAL (png_structp png_ptr, png_infop  info_ptr,  png_charp
749       unit, double width, double height);
750
751
752
753       void png_set_shift (png_structp png_ptr, png_color_8p true_bits);
754
755
756
757       void png_set_sig_bytes (png_structp png_ptr, int num_bytes);
758
759
760
761       void    png_set_sPLT    (png_structp   png_ptr,   png_infop   info_ptr,
762       png_spalette_p splt_ptr, int num_spalettes);
763
764
765
766       void  png_set_sRGB  (png_structp  png_ptr,  png_infop   info_ptr,   int
767       intent);
768
769
770
771       void   png_set_sRGB_gAMA_and_cHRM   (png_structp   png_ptr,   png_infop
772       info_ptr, int intent);
773
774
775
776       void png_set_strip_16 (png_structp png_ptr);
777
778
779
780       void png_set_strip_alpha (png_structp png_ptr);
781
782
783
784       void png_set_swap (png_structp png_ptr);
785
786
787
788       void png_set_swap_alpha (png_structp png_ptr);
789
790
791
792       void png_set_text (png_structp png_ptr, png_infop  info_ptr,  png_textp
793       text_ptr, int num_text);
794
795
796
797       void  png_set_tIME  (png_structp png_ptr, png_infop info_ptr, png_timep
798       mod_time);
799
800
801
802       void png_set_tRNS (png_structp png_ptr, png_infop  info_ptr,  png_bytep
803       trans, int num_trans, png_color_16p trans_values);
804
805
806
807       void png_set_tRNS_to_alpha(png_structp png_ptr);
808
809
810
811       png_uint_32   png_set_unknown_chunks  (png_structp  png_ptr,  png_infop
812       info_ptr, png_unknown_chunkp unknowns, int num, int location);
813
814
815
816       void  png_set_unknown_chunk_location(png_structp   png_ptr,   png_infop
817       info_ptr, int chunk, int location);
818
819
820
821       void   png_set_read_user_chunk_fn   (png_structp   png_ptr,   png_voidp
822       user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn);
823
824
825
826       void    png_set_user_limits    (png_structp    png_ptr,     png_uint_32
827       user_width_max, png_uint_32 user_height_max);
828
829
830
831       void   png_set_user_transform_info   (png_structp   png_ptr,  png_voidp
832       user_transform_ptr, int user_transform_depth, int  user_transform_chan‐
833       nels);
834
835
836
837       void   png_set_write_fn   (png_structp   png_ptr,   png_voidp   io_ptr,
838       png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn);
839
840
841
842       void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr
843       write_row_fn);
844
845
846
847       void      png_set_write_user_transform_fn     (png_structp     png_ptr,
848       png_user_transform_ptr write_user_transform_fn);
849
850
851
852       void png_set_compression_buffer_size(png_structp  png_ptr,  png_uint_32
853       size);
854
855
856
857       int   png_sig_cmp   (png_bytep   sig,   png_size_t   start,  png_size_t
858       num_to_check);
859
860
861
862       void png_start_read_image (png_structp png_ptr);
863
864
865
866       void png_warning (png_structp png_ptr, png_const_charp message);
867
868
869
870       void  png_write_chunk  (png_structp  png_ptr,   png_bytep   chunk_name,
871       png_bytep data, png_size_t length);
872
873
874
875       void   png_write_chunk_data   (png_structp   png_ptr,  png_bytep  data,
876       png_size_t length);
877
878
879
880       void png_write_chunk_end (png_structp png_ptr);
881
882
883
884       void png_write_chunk_start (png_structp png_ptr, png_bytep  chunk_name,
885       png_uint_32 length);
886
887
888
889       void png_write_destroy (png_structp png_ptr);
890
891
892
893       void png_write_end (png_structp png_ptr, png_infop info_ptr);
894
895
896
897       void png_write_flush (png_structp png_ptr);
898
899
900
901       void png_write_image (png_structp png_ptr, png_bytepp image);
902
903
904
905       DEPRECATED: void png_write_init (png_structp png_ptr);
906
907
908
909       DEPRECATED:     void     png_write_init_2     (png_structpp    ptr_ptr,
910       png_const_charp user_png_ver,  png_size_t  png_struct_size,  png_size_t
911       png_info_size);
912
913
914
915       void png_write_info (png_structp png_ptr, png_infop info_ptr);
916
917
918
919       void   png_write_info_before_PLTE   (png_structp   png_ptr,   png_infop
920       info_ptr);
921
922
923
924       void png_write_png (png_structp png_ptr, png_infop info_ptr, int trans‐
925       forms, png_voidp params);
926
927
928
929       void png_write_row (png_structp png_ptr, png_bytep row);
930
931
932
933       void  png_write_rows  (png_structp png_ptr, png_bytepp row, png_uint_32
934       num_rows);
935
936
937
938       voidpf png_zalloc (voidpf png_ptr, uInt items, uInt size);
939
940
941
942       void png_zfree (voidpf png_ptr, voidpf ptr);
943
944
945
946

DESCRIPTION

948       The libpng library supports encoding, decoding, and  various  manipula‐
949       tions  of  the  Portable Network Graphics (PNG) format image files.  It
950       uses the zlib(3) compression library.   Following  is  a  copy  of  the
951       libpng.txt file that accompanies libpng.
952

LIBPNG.TXT

954       libpng.txt - A description on how to use and modify libpng
955
956        libpng version 1.2.46 - July 9, 2011
957        Updated and distributed by Glenn Randers-Pehrson
958        <glennrp at users.sourceforge.net>
959        Copyright (c) 1998-2009 Glenn Randers-Pehrson
960
961        This document is released under the libpng license.
962        For conditions of distribution and use, see the disclaimer
963        and license in png.h
964
965        Based on:
966
967        libpng versions 0.97, January 1998, through 1.2.46 - July 9, 2011
968        Updated and distributed by Glenn Randers-Pehrson
969        Copyright (c) 1998-2009 Glenn Randers-Pehrson
970
971        libpng 1.0 beta 6  version 0.96 May 28, 1997
972        Updated and distributed by Andreas Dilger
973        Copyright (c) 1996, 1997 Andreas Dilger
974
975        libpng 1.0 beta 2 - version 0.88  January 26, 1996
976        For conditions of distribution and use, see copyright
977        notice in png.h. Copyright (c) 1995, 1996 Guy Eric
978        Schalnat, Group 42, Inc.
979
980        Updated/rewritten per request in the libpng FAQ
981        Copyright (c) 1995, 1996 Frank J. T. Wojcik
982        December 18, 1995 & January 20, 1996
983
984

I. Introduction

986       This  file  describes  how  to use and modify the PNG reference library
987       (known as libpng) for your own use.  There are five  sections  to  this
988       file:  introduction, structures, reading, writing, and modification and
989       configuration notes for various special platforms.  In addition to this
990       file,  example.c  is a good starting point for using the library, as it
991       is heavily commented and should include  everything  most  people  will
992       need.  We assume that libpng is already installed; see the INSTALL file
993       for instructions on how to install libpng.
994
995       For examples of libpng usage, see the files  "example.c",  "pngtest.c",
996       and  the files in the "contrib" directory, all of which are included in
997       the libpng distribution.
998
999       Libpng was written as a companion to the PNG specification, as a way of
1000       reducing the amount of time and effort it takes to support the PNG file
1001       format in application programs.
1002
1003       The PNG specification (second edition), November 2003, is available  as
1004       a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
1005       <http://www.w3.org/TR/2003/REC-PNG-20031110/ The W3C and ISO  documents
1006       have identical technical content.
1007
1008       The       PNG-1.2       specification       is       available       at
1009       <http://www.libpng.org/pub/png/documents/>.  It is technically  equiva‐
1010       lent  to the PNG specification (second edition) but has some additional
1011       material.
1012
1013       The    PNG-1.0    specification    is    available    as    RFC    2083
1014       <http://www.libpng.org/pub/png/documents/>  and as a W3C Recommendation
1015       <http://www.w3.org/TR/REC.png.html>.
1016
1017       Some additional chunks are  described  in  the  special-purpose  public
1018       chunks documents at <http://www.libpng.org/pub/png/documents/>.
1019
1020       Other  information  about PNG, and the latest version of libpng, can be
1021       found at the PNG home page, <http://www.libpng.org/pub/png/>.
1022
1023       Most users will not have to modify the library significantly;  advanced
1024       users may want to modify it more.  All attempts were made to make it as
1025       complete as possible, while keeping the code easy to understand.   Cur‐
1026       rently,  this  library only supports C.  Support for other languages is
1027       being considered.
1028
1029       Libpng has been designed to handle multiple sessions at one time, to be
1030       easily  modifiable,  to  be  portable  to the vast majority of machines
1031       (ANSI, K&R, 16-, 32-, and 64-bit) available, and to  be  easy  to  use.
1032       The  ultimate  goal  of  libpng is to promote the acceptance of the PNG
1033       file format in whatever way possible.  While there is still work to  be
1034       done (see the TODO file), libpng should cover the majority of the needs
1035       of its users.
1036
1037       Libpng uses zlib for its compression and decompression  of  PNG  files.
1038       Further  information about zlib, and the latest version of zlib, can be
1039       found     at     the     zlib     home     page,      <http://www.info-
1040       zip.org/pub/infozip/zlib/>.   The zlib compression utility is a general
1041       purpose utility that is useful for more than PNG files, and can be used
1042       without  libpng.   See  the  documentation delivered with zlib for more
1043       details.  You can usually find the source files for  the  zlib  utility
1044       wherever you find the libpng source files.
1045
1046       Libpng  is  thread  safe,  provided  the  threads  are  using different
1047       instances  of  the  structures.   Each  thread  should  have  its   own
1048       png_struct and png_info instances, and thus its own image.  Libpng does
1049       not protect itself against two threads using the  same  instance  of  a
1050       structure.
1051
1052

II. Structures

1054       There  are two main structures that are important to libpng, png_struct
1055       and png_info.  The first, png_struct, is  an  internal  structure  that
1056       will  not,  for  the  most  part, be used by a user except as the first
1057       variable passed to every libpng function call.
1058
1059       The png_info structure is designed to provide information about the PNG
1060       file.  At one time, the fields of png_info were intended to be directly
1061       accessible to the user.  However, this tended to  cause  problems  with
1062       applications  using dynamically loaded libraries, and as a result a set
1063       of interface functions for png_info (the  png_get_*()  and  png_set_*()
1064       functions)  was  developed.  The fields of png_info are still available
1065       for older applications, but it is suggested that applications  use  the
1066       new interfaces if at all possible.
1067
1068       Applications  that  do  make direct access to the members of png_struct
1069       (except for png_ptr->jmpbuf) must be recompiled whenever the library is
1070       updated,  and  applications  that  make direct access to the members of
1071       png_info must be recompiled if they were compiled or loaded with libpng
1072       version 1.0.6, in which the members were in a different order.  In ver‐
1073       sion 1.0.7, the members of the png_info structure reverted to  the  old
1074       order,  as  they  were  in versions 0.97c through 1.0.5.  Starting with
1075       version 2.0.0, both structures are going to be hidden, and the contents
1076       of  the  structures will only be accessible through the png_get/png_set
1077       functions.
1078
1079       The png.h header file is an invaluable reference for  programming  with
1080       libpng.   And  while I'm on the topic, make sure you include the libpng
1081       header file:
1082
1083       #include <png.h>
1084
1085

III. Reading

1087       We'll now walk you through the possible functions to call when  reading
1088       in  a  PNG file sequentially, briefly explaining the syntax and purpose
1089       of each one.  See example.c and png.h for more detail.  While  progres‐
1090       sive  reading  is covered in the next section, you will still need some
1091       of the functions discussed in this section to read a PNG file.
1092
1093
1094   Setup
1095       You will want to do the  I/O  initialization(*)  before  you  get  into
1096       libpng, so if it doesn't work, you don't have much to undo.  Of course,
1097       you will also want to insure that you are, in fact, dealing with a  PNG
1098       file.   Libpng  provides a simple check to see if a file is a PNG file.
1099       To use it, pass in the first 1 to 8 bytes of the file to  the  function
1100       png_sig_cmp(), and it will return 0 (false) if the bytes match the cor‐
1101       responding bytes of the PNG signature, or nonzero (true) otherwise.  Of
1102       course,  the  more  bytes  you pass in, the greater the accuracy of the
1103       prediction.
1104
1105       If you are intending to keep the file pointer open for use  in  libpng,
1106       you  must ensure you don't read more than 8 bytes from the beginning of
1107       the file, and you also have to make a call to  png_set_sig_bytes_read()
1108       with the number of bytes you read from the beginning.  Libpng will then
1109       only check the bytes (if any) that your program didn't read.
1110
1111       (*): If you are not using the standard I/O functions, you will need  to
1112       replace them with custom functions.  See the discussion under Customiz‐
1113       ing libpng.
1114
1115
1116           FILE *fp = fopen(file_name, "rb");
1117           if (!fp)
1118           {
1119               return (ERROR);
1120           }
1121           fread(header, 1, number, fp);
1122           is_png = !png_sig_cmp(header, 0, number);
1123           if (!is_png)
1124           {
1125               return (NOT_PNG);
1126           }
1127
1128
1129       Next, png_struct and png_info need to be allocated and initialized.  In
1130       order  to ensure that the size of these structures is correct even with
1131       a dynamically linked libpng, there  are  functions  to  initialize  and
1132       allocate  the  structures.   We also pass the library version, optional
1133       pointers to error handling functions, and a pointer to  a  data  struct
1134       for use by the error functions, if necessary (the pointer and functions
1135       can be NULL if the default error handlers are to  be  used).   See  the
1136       section  on  Changes  to  Libpng below regarding the old initialization
1137       functions.  The structure allocation functions quietly return  NULL  if
1138       they fail to create the structure, so your application should check for
1139       that.
1140
1141           png_structp png_ptr = png_create_read_struct
1142              (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1143               user_error_fn, user_warning_fn);
1144           if (!png_ptr)
1145               return (ERROR);
1146
1147           png_infop info_ptr = png_create_info_struct(png_ptr);
1148           if (!info_ptr)
1149           {
1150               png_destroy_read_struct(&png_ptr,
1151                  (png_infopp)NULL, (png_infopp)NULL);
1152               return (ERROR);
1153           }
1154
1155           png_infop end_info = png_create_info_struct(png_ptr);
1156           if (!end_info)
1157           {
1158               png_destroy_read_struct(&png_ptr, &info_ptr,
1159                 (png_infopp)NULL);
1160               return (ERROR);
1161           }
1162
1163       If you  want  to  use  your  own  memory  allocation  routines,  define
1164       PNG_USER_MEM_SUPPORTED  and  use  png_create_read_struct_2() instead of
1165       png_create_read_struct():
1166
1167           png_structp png_ptr = png_create_read_struct_2
1168              (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1169               user_error_fn, user_warning_fn, (png_voidp)
1170               user_mem_ptr, user_malloc_fn, user_free_fn);
1171
1172       The error handling routines passed to png_create_read_struct() and  the
1173       memory  alloc/free  routines  passed  to png_create_struct_2() are only
1174       necessary if you are not using the libpng supplied error  handling  and
1175       memory alloc/free functions.
1176
1177       When  libpng  encounters  an  error, it expects to longjmp back to your
1178       routine.  Therefore, you  will  need  to  call  setjmp  and  pass  your
1179       png_jmpbuf(png_ptr).  If you read the file from different routines, you
1180       will need to update the jmpbuf field every time you enter a new routine
1181       that will call a png_*() function.
1182
1183       See  your  documentation  of  setjmp/longjmp for your compiler for more
1184       information on setjmp/longjmp.  See the discussion on libpng error han‐
1185       dling  in  the Customizing Libpng section below for more information on
1186       the libpng error handling.  If an error occurs,  and  libpng  longjmp's
1187       back to your setjmp, you will want to call png_destroy_read_struct() to
1188       free any memory.
1189
1190           if (setjmp(png_jmpbuf(png_ptr)))
1191           {
1192               png_destroy_read_struct(&png_ptr, &info_ptr,
1193                  &end_info);
1194               fclose(fp);
1195               return (ERROR);
1196           }
1197
1198       If you would rather avoid the complexity of setjmp/longjmp issues,  you
1199       can  compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case errors
1200       will result in a call to PNG_ABORT() which defaults to abort().
1201
1202       Now you need to set up the input code.  The default for  libpng  is  to
1203       use  the  C function fread().  If you use this, you will need to pass a
1204       valid FILE * in the function png_init_io().  Be sure that the  file  is
1205       opened  in  binary mode.  If you wish to handle reading data in another
1206       way, you need not call the png_init_io() function, but  you  must  then
1207       implement  the  libpng  I/O methods discussed in the Customizing Libpng
1208       section below.
1209
1210           png_init_io(png_ptr, fp);
1211
1212       If you had previously opened the file and read  any  of  the  signature
1213       from  the beginning in order to see if this was a PNG file, you need to
1214       let libpng know that there are some bytes missing from the start of the
1215       file.
1216
1217           png_set_sig_bytes(png_ptr, number);
1218
1219
1220   Setting up callback code
1221       You  can set up a callback function to handle any unknown chunks in the
1222       input stream. You must supply the function
1223
1224           read_chunk_callback(png_ptr ptr,
1225                png_unknown_chunkp chunk);
1226           {
1227              /* The unknown chunk structure contains your
1228                 chunk data, along with similar data for any other
1229                 unknown chunks: */
1230
1231                  png_byte name[5];
1232                  png_byte *data;
1233                  png_size_t size;
1234
1235              /* Note that libpng has already taken care of
1236                 the CRC handling */
1237
1238              /* put your code here.  Search for your chunk in the
1239                 unknown chunk structure, process it, and return one
1240                 of the following: */
1241
1242              return (-n); /* chunk had an error */
1243              return (0); /* did not recognize */
1244              return (n); /* success */
1245           }
1246
1247       (You can give your function another  name  that  you  like  instead  of
1248       "read_chunk_callback")
1249
1250       To inform libpng about your function, use
1251
1252           png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1253               read_chunk_callback);
1254
1255       This names not only the callback function, but also a user pointer that
1256       you can retrieve with
1257
1258           png_get_user_chunk_ptr(png_ptr);
1259
1260       If you call the png_set_read_user_chunk_fn() function, then all unknown
1261       chunks  will  be  saved  when read, in case your callback function will
1262       need one or more of them.   This  behavior  can  be  changed  with  the
1263       png_set_keep_unknown_chunks() function, described below.
1264
1265       At  this  point, you can set up a callback function that will be called
1266       after each row has been read, which you can use to control  a  progress
1267       meter  or the like.  It's demonstrated in pngtest.c.  You must supply a
1268       function
1269
1270           void read_row_callback(png_ptr ptr, png_uint_32 row,
1271              int pass);
1272           {
1273             /* put your code here */
1274           }
1275
1276       (You can give it another name that you like instead of  "read_row_call‐
1277       back")
1278
1279       To inform libpng about your function, use
1280
1281           png_set_read_status_fn(png_ptr, read_row_callback);
1282
1283
1284   Unknown-chunk handling
1285       Now  you get to set the way the library processes unknown chunks in the
1286       input PNG stream. Both known and unknown chunks will be  read.   Normal
1287       behavior  is that known chunks will be parsed into information in vari‐
1288       ous info_ptr members while  unknown  chunks  will  be  discarded.  This
1289       behavior  can be wasteful if your application will never use some known
1290       chunk types. To change this, you can call:
1291
1292           png_set_keep_unknown_chunks(png_ptr, keep,
1293               chunk_list, num_chunks);
1294           keep       - 0: default unknown chunk handling
1295                        1: ignore; do not keep
1296                        2: keep only if safe-to-copy
1297                        3: keep even if unsafe-to-copy
1298                      You can use these definitions:
1299                        PNG_HANDLE_CHUNK_AS_DEFAULT   0
1300                        PNG_HANDLE_CHUNK_NEVER        1
1301                        PNG_HANDLE_CHUNK_IF_SAFE      2
1302                        PNG_HANDLE_CHUNK_ALWAYS       3
1303           chunk_list - list of chunks affected (a byte string,
1304                        five bytes per chunk, NULL or ' ' if
1305                        num_chunks is 0)
1306           num_chunks - number of chunks affected; if 0, all
1307                        unknown chunks are affected.  If nonzero,
1308                        only the chunks in the list are affected
1309
1310       Unknown chunks declared in this way will be saved as raw  data  onto  a
1311       list  of  png_unknown_chunk  structures.   If  a chunk that is normally
1312       known to libpng is named in the list, it will be  handled  as  unknown,
1313       according  to  the "keep" directive.  If a chunk is named in successive
1314       instances of png_set_keep_unknown_chunks(),  the  final  instance  will
1315       take  precedence.   The  IHDR  and  IEND  chunks should not be named in
1316       chunk_list; if they are, libpng will process them normally anyway.
1317
1318       Here is an example of the usage of png_set_keep_unknown_chunks(), where
1319       the  private "vpAg" chunk will later be processed by a user chunk call‐
1320       back function:
1321
1322           png_byte vpAg[5]={118, 112,  65, 103, (png_byte) ' '};
1323
1324           #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1325             png_byte unused_chunks[]=
1326             {
1327               104,  73,  83,  84, (png_byte) ' ',   /* hIST */
1328               105,  84,  88, 116, (png_byte) ' ',   /* iTXt */
1329               112,  67,  65,  76, (png_byte) ' ',   /* pCAL */
1330               115,  67,  65,  76, (png_byte) ' ',   /* sCAL */
1331               115,  80,  76,  84, (png_byte) ' ',   /* sPLT */
1332               116,  73,  77,  69, (png_byte) ' ',   /* tIME */
1333             };
1334           #endif
1335
1336           ...
1337
1338           #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1339             /* ignore all unknown chunks: */
1340             png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
1341             /* except for vpAg: */
1342             png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
1343             /* also ignore unused known chunks: */
1344             png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
1345                (int)sizeof(unused_chunks)/5);
1346           #endif
1347
1348
1349   User limits
1350       The PNG specification allows the width and height of an image to be  as
1351       large  as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1352       Since very few applications really need to process such  large  images,
1353       we  have  imposed  an  arbitrary  1-million  limit on rows and columns.
1354       Larger images will be rejected immediately with a png_error() call.  If
1355       you wish to override this limit, you can use
1356
1357          png_set_user_limits(png_ptr, width_max, height_max);
1358
1359       to  set your own limits, or use width_max = height_max = 0x7fffffffL to
1360       allow all valid dimensions (libpng may reject some  very  large  images
1361       anyway because of potential buffer overflow conditions).
1362
1363       You  should  put  this statement after you create the PNG structure and
1364       before calling png_read_info(), png_read_png(), or  png_process_data().
1365       If you need to retrieve the limits that are being applied, use
1366
1367          width_max = png_get_user_width_max(png_ptr);
1368          height_max = png_get_user_height_max(png_ptr);
1369
1370       The  PNG  specification sets no limit on the number of ancillary chunks
1371       allowed in a PNG datastream.  You can impose a limit on the total  num‐
1372       ber  of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored,
1373       with
1374
1375          png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
1376
1377       where 0x7fffffffL means unlimited.  You can retrieve this limit with
1378
1379          chunk_cache_max = png_get_chunk_cache_max(png_ptr);
1380
1381       This limit also applies to the number of buffers that can be  allocated
1382       by  png_decompress_chunk()  while  decompressing  iTXt,  zTXt, and iCCP
1383       chunks.
1384
1385
1386   The high-level read interface
1387       At this point there are two ways to  proceed;  through  the  high-level
1388       read  interface,  or  through  a sequence of low-level read operations.
1389       You can use the high-level interface if (a) you are willing to read the
1390       entire image into memory, and (b) the input transformations you want to
1391       do are limited to the following set:
1392
1393           PNG_TRANSFORM_IDENTITY      No transformation
1394           PNG_TRANSFORM_STRIP_16      Strip 16-bit samples to
1395                                       8 bits
1396           PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
1397           PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit
1398                                       samples to bytes
1399           PNG_TRANSFORM_PACKSWAP      Change order of packed
1400                                       pixels to LSB first
1401           PNG_TRANSFORM_EXPAND        Perform set_expand()
1402           PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
1403           PNG_TRANSFORM_SHIFT         Normalize pixels to the
1404                                       sBIT depth
1405           PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
1406                                       to BGRA
1407           PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
1408                                       to AG
1409           PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
1410                                       to transparency
1411           PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
1412           PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
1413                                       to RGB (or GA to RGBA)
1414
1415       (This excludes setting a background color, doing gamma  transformation,
1416       dithering, and setting filler.)  If this is the case, simply do this:
1417
1418           png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1419
1420       where  png_transforms  is  an integer containing the bitwise OR of some
1421       set  of   transformation   flags.    This   call   is   equivalent   to
1422       png_read_info(),  followed  the set of transformations indicated by the
1423       transform mask, then png_read_image(), and finally png_read_end().
1424
1425       (The final parameter of this call is not yet used.   Someday  it  might
1426       point to transformation parameters required by some future input trans‐
1427       form.)
1428
1429       You must use png_transforms and not call any png_set_transform()  func‐
1430       tions when you use png_read_png().
1431
1432       After  you  have called png_read_png(), you can retrieve the image data
1433       with
1434
1435          row_pointers = png_get_rows(png_ptr, info_ptr);
1436
1437       where row_pointers is an array of pointers to the pixel data  for  each
1438       row:
1439
1440          png_bytep row_pointers[height];
1441
1442       If you know your image size and pixel size ahead of time, you can allo‐
1443       cate row_pointers prior to calling png_read_png() with
1444
1445          if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
1446             png_error (png_ptr,
1447                "Image is too tall to process in memory");
1448          if (width > PNG_UINT_32_MAX/pixel_size)
1449             png_error (png_ptr,
1450                "Image is too wide to process in memory");
1451          row_pointers = png_malloc(png_ptr,
1452             height*png_sizeof(png_bytep));
1453          for (int i=0; i<height, i++)
1454             row_pointers[i]=NULL;  /* security precaution */
1455          for (int i=0; i<height, i++)
1456             row_pointers[i]=png_malloc(png_ptr,
1457                width*pixel_size);
1458          png_set_rows(png_ptr, info_ptr, &row_pointers);
1459
1460       Alternatively you could allocate your image in one big block and define
1461       row_pointers[i] to point into the proper places in your block.
1462
1463       If  you  use png_set_rows(), the application is responsible for freeing
1464       row_pointers (and row_pointers[i], if they were separately allocated).
1465
1466       If you don't allocate row_pointers ahead of time,  png_read_png()  will
1467       do it, and it'll be free'ed when you call png_destroy_*().
1468
1469
1470   The low-level read interface
1471       If you are going the low-level route, you are now ready to read all the
1472       file information up to the actual image data.  You do this with a  call
1473       to png_read_info().
1474
1475           png_read_info(png_ptr, info_ptr);
1476
1477       This will process all chunks up to but not including the image data.
1478
1479
1480   Querying the info structure
1481       Functions are used to get the information from the info_ptr once it has
1482       been read.  Note that these fields may  not  be  completely  filled  in
1483       until png_read_end() has read the chunk data following the image.
1484
1485           png_get_IHDR(png_ptr, info_ptr, &width, &height,
1486              &bit_depth, &color_type, &interlace_type,
1487              &compression_type, &filter_method);
1488
1489           width          - holds the width of the image
1490                            in pixels (up to 2^31).
1491           height         - holds the height of the image
1492                            in pixels (up to 2^31).
1493           bit_depth      - holds the bit depth of one of the
1494                            image channels.  (valid values are
1495                            1, 2, 4, 8, 16 and depend also on
1496                            the color_type.  See also
1497                            significant bits (sBIT) below).
1498           color_type     - describes which color/alpha channels
1499                                are present.
1500                            PNG_COLOR_TYPE_GRAY
1501                               (bit depths 1, 2, 4, 8, 16)
1502                            PNG_COLOR_TYPE_GRAY_ALPHA
1503                               (bit depths 8, 16)
1504                            PNG_COLOR_TYPE_PALETTE
1505                               (bit depths 1, 2, 4, 8)
1506                            PNG_COLOR_TYPE_RGB
1507                               (bit_depths 8, 16)
1508                            PNG_COLOR_TYPE_RGB_ALPHA
1509                               (bit_depths 8, 16)
1510
1511                            PNG_COLOR_MASK_PALETTE
1512                            PNG_COLOR_MASK_COLOR
1513                            PNG_COLOR_MASK_ALPHA
1514
1515           filter_method  - (must be PNG_FILTER_TYPE_BASE
1516                            for PNG 1.0, and can also be
1517                            PNG_INTRAPIXEL_DIFFERENCING if
1518                            the PNG datastream is embedded in
1519                            a MNG-1.0 datastream)
1520           compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1521                            for PNG 1.0)
1522           interlace_type - (PNG_INTERLACE_NONE or
1523                            PNG_INTERLACE_ADAM7)
1524
1525           Any or all of interlace_type, compression_type, or
1526           filter_method can be NULL if you are
1527           not interested in their values.
1528
1529           Note that png_get_IHDR() returns 32-bit data into
1530           the application's width and height variables.
1531           This is an unsafe situation if these are 16-bit
1532           variables.  In such situations, the
1533           png_get_image_width() and png_get_image_height()
1534           functions described below are safer.
1535
1536           width            = png_get_image_width(png_ptr,
1537                                info_ptr);
1538           height           = png_get_image_height(png_ptr,
1539                                info_ptr);
1540           bit_depth        = png_get_bit_depth(png_ptr,
1541                                info_ptr);
1542           color_type       = png_get_color_type(png_ptr,
1543                                info_ptr);
1544           filter_method    = png_get_filter_type(png_ptr,
1545                                info_ptr);
1546           compression_type = png_get_compression_type(png_ptr,
1547                                info_ptr);
1548           interlace_type   = png_get_interlace_type(png_ptr,
1549                                info_ptr);
1550
1551           channels = png_get_channels(png_ptr, info_ptr);
1552           channels       - number of channels of info for the
1553                            color type (valid values are 1 (GRAY,
1554                            PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1555                            4 (RGB_ALPHA or RGB + filler byte))
1556           rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1557           rowbytes       - number of bytes needed to hold a row
1558
1559           signature = png_get_signature(png_ptr, info_ptr);
1560           signature      - holds the signature read from the
1561                            file (if any).  The data is kept in
1562                            the same offset it would be if the
1563                            whole signature were read (i.e. if an
1564                            application had already read in 4
1565                            bytes of signature before starting
1566                            libpng, the remaining 4 bytes would
1567                            be in signature[4] through signature[7]
1568                            (see png_set_sig_bytes())).
1569
1570       These  are  also  important,  but their validity depends on whether the
1571       chunk   has   been   read.    The   png_get_valid(png_ptr,    info_ptr,
1572       PNG_INFO_<chunk>) and png_get_<chunk>(png_ptr, info_ptr, ...) functions
1573       return non-zero if the data has been read, or zero if  it  is  missing.
1574       The parameters to the png_get_<chunk> are set directly if they are sim‐
1575       ple data types, or a pointer into the info_ptr is returned for any com‐
1576       plex types.
1577
1578           png_get_PLTE(png_ptr, info_ptr, &palette,
1579                            &num_palette);
1580           palette        - the palette for the file
1581                            (array of png_color)
1582           num_palette    - number of entries in the palette
1583
1584           png_get_gAMA(png_ptr, info_ptr, &gamma);
1585           gamma          - the gamma the file is written
1586                            at (PNG_INFO_gAMA)
1587
1588           png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1589           srgb_intent    - the rendering intent (PNG_INFO_sRGB)
1590                            The presence of the sRGB chunk
1591                            means that the pixel data is in the
1592                            sRGB color space.  This chunk also
1593                            implies specific values of gAMA and
1594                            cHRM.
1595
1596           png_get_iCCP(png_ptr, info_ptr, &name,
1597              &compression_type, &profile, &proflen);
1598           name            - The profile name.
1599           compression     - The compression type; always
1600                             PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1601                             You may give NULL to this argument to
1602                             ignore it.
1603           profile         - International Color Consortium color
1604                             profile data. May contain NULs.
1605           proflen         - length of profile data in bytes.
1606
1607           png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1608           sig_bit        - the number of significant bits for
1609                            (PNG_INFO_sBIT) each of the gray,
1610                            red, green, and blue channels,
1611                            whichever are appropriate for the
1612                            given color type (png_color_16)
1613
1614           png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
1615                            &trans_values);
1616           trans          - array of transparent
1617                            entries for palette (PNG_INFO_tRNS)
1618           trans_values   - graylevel or color sample values of
1619                            the single transparent color for
1620                            non-paletted images (PNG_INFO_tRNS)
1621           num_trans      - number of transparent entries
1622                            (PNG_INFO_tRNS)
1623
1624           png_get_hIST(png_ptr, info_ptr, &hist);
1625                            (PNG_INFO_hIST)
1626           hist           - histogram of palette (array of
1627                            png_uint_16)
1628
1629           png_get_tIME(png_ptr, info_ptr, &mod_time);
1630           mod_time       - time image was last modified
1631                           (PNG_VALID_tIME)
1632
1633           png_get_bKGD(png_ptr, info_ptr, &background);
1634           background     - background color (PNG_VALID_bKGD)
1635                            valid 16-bit red, green and blue
1636                            values, regardless of color_type
1637
1638           num_comments   = png_get_text(png_ptr, info_ptr,
1639                            &text_ptr, &num_text);
1640           num_comments   - number of comments
1641           text_ptr       - array of png_text holding image
1642                            comments
1643           text_ptr[i].compression - type of compression used
1644                        on "text" PNG_TEXT_COMPRESSION_NONE
1645                                  PNG_TEXT_COMPRESSION_zTXt
1646                                  PNG_ITXT_COMPRESSION_NONE
1647                                  PNG_ITXT_COMPRESSION_zTXt
1648           text_ptr[i].key   - keyword for comment.  Must contain
1649                                1-79 characters.
1650           text_ptr[i].text  - text comments for current
1651                                keyword.  Can be empty.
1652           text_ptr[i].text_length - length of text string,
1653                        after decompression, 0 for iTXt
1654           text_ptr[i].itxt_length - length of itxt string,
1655                        after decompression, 0 for tEXt/zTXt
1656           text_ptr[i].lang  - language of comment (empty
1657                                string for unknown).
1658           text_ptr[i].lang_key  - keyword in UTF-8
1659                                (empty string for unknown).
1660           Note that the itxt_length, lang, and lang_key
1661           members of the text_ptr structure only exist
1662           when the library is built with iTXt chunk support.
1663
1664           num_text       - number of comments (same as
1665                            num_comments; you can put NULL here
1666                            to avoid the duplication)
1667           Note while png_set_text() will accept text, language,
1668           and translated keywords that can be NULL pointers, the
1669           structure returned by png_get_text will always contain
1670           regular zero-terminated C strings.  They might be
1671           empty strings but they will never be NULL pointers.
1672
1673           num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1674              &palette_ptr);
1675           palette_ptr    - array of palette structures holding
1676                            contents of one or more sPLT chunks
1677                            read.
1678           num_spalettes  - number of sPLT chunks read.
1679
1680           png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1681              &unit_type);
1682           offset_x       - positive offset from the left edge
1683                            of the screen
1684           offset_y       - positive offset from the top edge
1685                            of the screen
1686           unit_type      - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1687
1688           png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1689              &unit_type);
1690           res_x          - pixels/unit physical resolution in
1691                            x direction
1692           res_y          - pixels/unit physical resolution in
1693                            x direction
1694           unit_type      - PNG_RESOLUTION_UNKNOWN,
1695                            PNG_RESOLUTION_METER
1696
1697           png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1698              &height)
1699           unit        - physical scale units (an integer)
1700           width       - width of a pixel in physical scale units
1701           height      - height of a pixel in physical scale units
1702                        (width and height are doubles)
1703
1704           png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1705              &height)
1706           unit        - physical scale units (an integer)
1707           width       - width of a pixel in physical scale units
1708           height      - height of a pixel in physical scale units
1709                        (width and height are strings like "2.54")
1710
1711           num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1712              info_ptr, &unknowns)
1713           unknowns          - array of png_unknown_chunk
1714                               structures holding unknown chunks
1715           unknowns[i].name  - name of unknown chunk
1716           unknowns[i].data  - data of unknown chunk
1717           unknowns[i].size  - size of unknown chunk's data
1718           unknowns[i].location - position of chunk in file
1719
1720           The value of "i" corresponds to the order in which the
1721           chunks were read from the PNG file or inserted with the
1722           png_set_unknown_chunks() function.
1723
1724       The  data  from  the  pHYs chunk can be retrieved in several convenient
1725       forms:
1726
1727           res_x = png_get_x_pixels_per_meter(png_ptr,
1728              info_ptr)
1729           res_y = png_get_y_pixels_per_meter(png_ptr,
1730              info_ptr)
1731           res_x_and_y = png_get_pixels_per_meter(png_ptr,
1732              info_ptr)
1733           res_x = png_get_x_pixels_per_inch(png_ptr,
1734              info_ptr)
1735           res_y = png_get_y_pixels_per_inch(png_ptr,
1736              info_ptr)
1737           res_x_and_y = png_get_pixels_per_inch(png_ptr,
1738              info_ptr)
1739           aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1740              info_ptr)
1741
1742          (Each of these returns 0 [signifying "unknown"] if
1743              the data is not present or if res_x is 0;
1744              res_x_and_y is 0 if res_x != res_y)
1745
1746       The data from the oFFs chunk can be  retrieved  in  several  convenient
1747       forms:
1748
1749           x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1750           y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1751           x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1752           y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1753
1754          (Each of these returns 0 [signifying "unknown" if both
1755              x and y are 0] if the data is not present or if the
1756              chunk is present but the unit is the pixel)
1757
1758       For  more information, see the png_info definition in png.h and the PNG
1759       specification for chunk contents.  Be careful with  trusting  rowbytes,
1760       as  some of the transformations could increase the space needed to hold
1761       a row (expand, filler, gray_to_rgb, etc.).  See png_read_update_info(),
1762       below.
1763
1764       A  quick word about text_ptr and num_text.  PNG stores comments in key‐
1765       word/text pairs, one pair per chunk, with no limit  on  the  number  of
1766       text chunks, and a 2^31 byte limit on their size.  While there are sug‐
1767       gested keywords, there is no requirement to restrict the use  to  these
1768       strings.   It  is strongly suggested that keywords and text be sensible
1769       to humans (that's the point), so don't use abbreviations.  Non-printing
1770       symbols  are  not allowed.  See the PNG specification for more details.
1771       There is also no requirement to have text after the keyword.
1772
1773       Keywords should be limited to 79 Latin-1 characters without leading  or
1774       trailing spaces, but non-consecutive spaces are allowed within the key‐
1775       word.  It is possible to have the same keyword  any  number  of  times.
1776       The text_ptr is an array of png_text structures, each holding a pointer
1777       to a language string, a pointer to a keyword and a pointer  to  a  text
1778       string.   The text string, language code, and translated keyword may be
1779       empty or NULL pointers.  The keyword/text pairs are put into the  array
1780       in  the order that they are received.  However, some or all of the text
1781       chunks may be after the image, so, to make sure you have read  all  the
1782       text chunks, don't mess with these until after you read the stuff after
1783       the image.  This will be mentioned again below in the  discussion  that
1784       goes with png_read_end().
1785
1786
1787   Input transformations
1788       After you've read the header information, you can set up the library to
1789       handle any special transformations of the image data.  The various ways
1790       to  transform  the data will be described in the order that they should
1791       occur.  This is important, as some  of  these  change  the  color  type
1792       and/or  bit  depth  of  the  data, and some others only work on certain
1793       color types and bit depths.  Even though each transformation checks  to
1794       see  if it has data that it can do something with, you should make sure
1795       to only enable a transformation if it will be valid for the data.   For
1796       example, don't swap red and blue on grayscale data.
1797
1798       The  colors  used  for the background and transparency values should be
1799       supplied in the same format/depth as the current image data.  They  are
1800       stored  in  the  same  format/depth as the image data in a bKGD or tRNS
1801       chunk, so this is what libpng expects for this data.   The  colors  are
1802       transformed  to  keep  in  sync with the image data when an application
1803       calls the png_read_update_info() routine (see below).
1804
1805       Data will be decoded into the supplied row buffers  packed  into  bytes
1806       unless  the  library has been told to transform it into another format.
1807       For example, 4 bit/pixel paletted or grayscale data will be returned  2
1808       pixels/byte with the leftmost pixel in the high-order bits of the byte,
1809       unless png_set_packing() is called.  8-bit RGB data will be  stored  in
1810       RGB  RGB  RGB  format unless png_set_filler() or png_set_add_alpha() is
1811       called to insert filler bytes, either before or after each RGB triplet.
1812       16-bit  RGB data will be returned RRGGBB RRGGBB, with the most signifi‐
1813       cant byte of the color value first, unless png_set_strip_16() is called
1814       to  transform  it  to  regular RGB RGB triplets, or png_set_filler() or
1815       png_set_add alpha() is called to insert filler bytes, either before  or
1816       after  each  RRGGBB triplet.  Similarly, 8-bit or 16-bit grayscale data
1817       can  be  modified  with   png_set_filler(),   png_set_add_alpha(),   or
1818       png_set_strip_16().
1819
1820       The  following  code  transforms  grayscale  images of less than 8 to 8
1821       bits, changes paletted images to RGB, and adds a full alpha channel  if
1822       there is transparency information in a tRNS chunk.  This is most useful
1823       on grayscale images with bit depths of 2 or 4 or if there is  a  multi‐
1824       ple-image  viewing  application  that wishes to treat all images in the
1825       same way.
1826
1827           if (color_type == PNG_COLOR_TYPE_PALETTE)
1828               png_set_palette_to_rgb(png_ptr);
1829
1830           if (color_type == PNG_COLOR_TYPE_GRAY &&
1831               bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
1832
1833           if (png_get_valid(png_ptr, info_ptr,
1834               PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1835
1836       These three functions are actually aliases for png_set_expand(),  added
1837       in  libpng  version  1.0.4, with the function names expanded to improve
1838       code readability.  In some future version they may actually do  differ‐
1839       ent things.
1840
1841       As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was added.
1842       It expands the sample depth without changing tRNS to alpha.
1843
1844       As of libpng version 1.2.46, not all possible expansions are supported.
1845
1846       In the following table, the 01 means grayscale with depth<8,  31  means
1847       indexed  with  depth<8,  other  numerals  represent the color type, "T"
1848       means the tRNS chunk is present, A means an alpha channel  is  present,
1849       and  O  means  tRNS or alpha is present but all pixels in the image are
1850       opaque.
1851
1852         FROM  01  31   0  0T  0O   2  2T  2O   3  3T  3O  4A  4O  6A  6O
1853          TO
1854          01    -
1855          31        -
1856           0    1       -
1857          0T                -
1858          0O                    -
1859           2           GX           -
1860          2T                            -
1861          2O                                -
1862           3        1                           -
1863          3T                                        -
1864          3O                                            -
1865          4A                T                               -
1866          4O                                                    -
1867          6A               GX         TX           TX               -
1868          6O                   GX                      TX               -
1869
1870       Within the matrix,
1871            "-" means the transformation is not supported.
1872            "X" means the transformation is obtained by png_set_expand().
1873            "1" means the transformation is obtained by
1874                png_set_expand_gray_1_2_4_to_8
1875            "G" means the transformation is obtained by
1876                png_set_gray_to_rgb().
1877            "P" means the transformation is obtained by
1878                png_set_expand_palette_to_rgb().
1879            "T" means the transformation is obtained by
1880                png_set_tRNS_to_alpha().
1881
1882       PNG can have files with 16 bits per channel.  If you only can handle  8
1883       bits per channel, this will strip the pixels down to 8 bit.
1884
1885           if (bit_depth == 16)
1886               png_set_strip_16(png_ptr);
1887
1888       If,  for some reason, you don't need the alpha channel on an image, and
1889       you want to remove it rather than combining it with the background (but
1890       the image author certainly had in mind that you *would* combine it with
1891       the background, so that's what you should probably do):
1892
1893           if (color_type & PNG_COLOR_MASK_ALPHA)
1894               png_set_strip_alpha(png_ptr);
1895
1896       In PNG files, the alpha channel in an image is the  level  of  opacity.
1897       If  you  need  the  alpha channel in an image to be the level of trans‐
1898       parency instead of opacity, you can invert the alpha  channel  (or  the
1899       tRNS chunk data) after it's read, so that 0 is fully opaque and 255 (in
1900       8-bit or paletted images) or 65535 (in 16-bit images) is  fully  trans‐
1901       parent, with
1902
1903           png_set_invert_alpha(png_ptr);
1904
1905       The  PNG format only supports pixels with postmultiplied alpha.  If you
1906       want to replace the pixels, after reading them, with pixels  that  have
1907       premultiplied color samples, you can do this with
1908
1909           png_set_premultiply_alpha(png_ptr);
1910
1911       If you do this, any input with a tRNS chunk will be expanded to have an
1912       alpha channel.
1913
1914       PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small  as
1915       they can, resulting in, for example, 8 pixels per byte for 1 bit files.
1916       This code expands to 1 pixel per byte without changing  the  values  of
1917       the pixels:
1918
1919           if (bit_depth < 8)
1920               png_set_packing(png_ptr);
1921
1922       PNG  files  have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
1923       stored in a PNG image have been "scaled" or "shifted" up  to  the  next
1924       higher  possible bit depth (e.g. from 5 bits/sample in the range [0,31]
1925       to 8 bits/sample in the range [0, 255]).  However, it is also  possible
1926       to  convert  the  PNG  pixel data back to the original bit depth of the
1927       image.  This call reduces the pixels back  down  to  the  original  bit
1928       depth:
1929
1930           png_color_8p sig_bit;
1931
1932           if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1933               png_set_shift(png_ptr, sig_bit);
1934
1935       PNG  files  store  3-color pixels in red, green, blue order.  This code
1936       changes the storage of the pixels to blue, green, red:
1937
1938           if (color_type == PNG_COLOR_TYPE_RGB ||
1939               color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1940               png_set_bgr(png_ptr);
1941
1942       PNG files store RGB pixels packed into 3 or 6 bytes. This code  expands
1943       them  into  4  or  8 bytes for windowing systems that need them in this
1944       format:
1945
1946           if (color_type == PNG_COLOR_TYPE_RGB)
1947               png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
1948
1949       where "filler" is the 8 or 16-bit number to fill with, and the location
1950       is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1951       you want the filler before the RGB or after.  This transformation  does
1952       not  affect  images  that  already have full alpha channels.  To add an
1953       opaque alpha channel, use filler=0xff or  0xffff  and  PNG_FILLER_AFTER
1954       which will generate RGBA pixels.
1955
1956       Note that png_set_filler() does not change the color type.  If you want
1957       to do that, you can add a true alpha channel with
1958
1959           if (color_type == PNG_COLOR_TYPE_RGB ||
1960                  color_type == PNG_COLOR_TYPE_GRAY)
1961           png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1962
1963       where "filler" contains the alpha value to assign to each pixel.   This
1964       function was added in libpng-1.2.7.
1965
1966       If  you  are  reading  an image with an alpha channel, and you need the
1967       data as ARGB instead of the normal PNG format RGBA:
1968
1969           if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1970               png_set_swap_alpha(png_ptr);
1971
1972       For some uses, you may want a grayscale image to be represented as RGB.
1973       This code will do that conversion:
1974
1975           if (color_type == PNG_COLOR_TYPE_GRAY ||
1976               color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1977                 png_set_gray_to_rgb(png_ptr);
1978
1979       Conversely,  you  can  convert  an  RGB  or  RGBA image to grayscale or
1980       grayscale with alpha.
1981
1982           if (color_type == PNG_COLOR_TYPE_RGB ||
1983               color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1984                 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1985                    int red_weight, int green_weight);
1986
1987           error_action = 1: silently do the conversion
1988           error_action = 2: issue a warning if the original
1989                             image has any pixel where
1990                             red != green or red != blue
1991           error_action = 3: issue an error and abort the
1992                             conversion if the original
1993                             image has any pixel where
1994                             red != green or red != blue
1995
1996           red_weight:       weight of red component times 100000
1997           green_weight:     weight of green component times 100000
1998                             If either weight is negative, default
1999                             weights (21268, 71514) are used.
2000
2001       If you have set error_action = 1 or 2, you can later check whether  the
2002       image  really  was  gray,  after  processing  the  image rows, with the
2003       png_get_rgb_to_gray_status(png_ptr)  function.   It   will   return   a
2004       png_byte that is zero if the image was gray or 1 if there were any non-
2005       gray pixels.   bKGD  and  sBIT  data  will  be  silently  converted  to
2006       grayscale, using the green channel data, regardless of the error_action
2007       setting.
2008
2009       With red_weight+green_weight<=100000, the normalized graylevel is  com‐
2010       puted:
2011
2012           int rw = red_weight * 65536;
2013           int gw = green_weight * 65536;
2014           int bw = 65536 - (rw + gw);
2015           gray = (rw*red + gw*green + bw*blue)/65536;
2016
2017       The  default  values approximate those recommended in the Charles Poyn‐
2018       ton's  Color  FAQ,  <http://www.inforamp.net/~poynton/>  Copyright  (c)
2019       1998-01-04 Charles Poynton <poynton at inforamp.net>
2020
2021           Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
2022
2023       Libpng approximates this with
2024
2025           Y = 0.21268 * R    + 0.7151 * G    + 0.07217 * B
2026
2027       which can be expressed with integers as
2028
2029           Y = (6969 * R + 23434 * G + 2365 * B)/32768
2030
2031       The  calculation  is done in a linear colorspace, if the image gamma is
2032       known.
2033
2034       If you have a  grayscale  and  you  are  using  png_set_expand_depth(),
2035       png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to a
2036       higher bit-depth, you must either supply the background color as a gray
2037       value  at  the original file bit-depth (need_expand = 1) or else supply
2038       the background color as an RGB triplet at the final, expanded bit depth
2039       (need_expand = 0).  Similarly, if you are reading a paletted image, you
2040       must either supply the background color as a palette index (need_expand
2041       =  1)  or  as  an  RGB  triplet  that  may or may not be in the palette
2042       (need_expand = 0).
2043
2044           png_color_16 my_background;
2045           png_color_16p image_background;
2046
2047           if (png_get_bKGD(png_ptr, info_ptr, &image_background))
2048               png_set_background(png_ptr, image_background,
2049                 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
2050           else
2051               png_set_background(png_ptr, &my_background,
2052                 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
2053
2054       The png_set_background() function tells libpng to composite images with
2055       alpha or simple transparency against the supplied background color.  If
2056       the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), you  may  use
2057       this  color, or supply another color more suitable for the current dis‐
2058       play (e.g., the background color from a web page).  You  need  to  tell
2059       libpng  whether  the  color  is  in  the  gamma  space  of  the display
2060       (PNG_BACKGROUND_GAMMA_SCREEN  for  colors   you   supply),   the   file
2061       (PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one that
2062       is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't  know
2063       why anyone would use this, but it's here).
2064
2065       To  properly  display PNG images on any kind of system, the application
2066       needs to know what the display gamma is.  Ideally, the user  will  know
2067       this,  and  the  application  will allow them to set it.  One method of
2068       allowing the user to set the display gamma separately for  each  system
2069       is  to  check for a SCREEN_GAMMA or DISPLAY_GAMMA environment variable,
2070       which will hopefully be correctly set.
2071
2072       Note that display_gamma is the overall  gamma  correction  required  to
2073       produce  pleasing  results, which depends on the lighting conditions in
2074       the surrounding environment.  In a dim or brightly lit room, no compen‐
2075       sation other than the physical gamma exponent of the monitor is needed,
2076       while in a dark room a slightly smaller exponent is better.
2077
2078          double gamma, screen_gamma;
2079
2080          if (/* We have a user-defined screen
2081              gamma value */)
2082          {
2083             screen_gamma = user_defined_screen_gamma;
2084          }
2085          /* One way that applications can share the same
2086             screen gamma value */
2087          else if ((gamma_str = getenv("SCREEN_GAMMA"))
2088             != NULL)
2089          {
2090             screen_gamma = (double)atof(gamma_str);
2091          }
2092          /* If we don't have another value */
2093          else
2094          {
2095             screen_gamma = 2.2; /* A good guess for a
2096                  PC monitor in a bright office or a dim room */
2097             screen_gamma = 2.0; /* A good guess for a
2098                  PC monitor in a dark room */
2099             screen_gamma = 1.7 or 1.0;  /* A good
2100                  guess for Mac systems */
2101          }
2102
2103       The png_set_gamma() function handles gamma transformations of the data.
2104       Pass  both  the  file  gamma and the current screen_gamma.  If the file
2105       does not have a gamma value, you can pass one anyway  if  you  have  an
2106       idea  what  it  is  (usually  0.45455 is a good guess for GIF images on
2107       PCs).  Note that file gammas are inverted from screen gammas.  See  the
2108       discussions on gamma in the PNG specification for an excellent descrip‐
2109       tion of what gamma is, and why all applications should support it.   It
2110       is strongly recommended that PNG viewers support gamma correction.
2111
2112          if (png_get_gAMA(png_ptr, info_ptr, &gamma))
2113             png_set_gamma(png_ptr, screen_gamma, gamma);
2114          else
2115             png_set_gamma(png_ptr, screen_gamma, 0.45455);
2116
2117       If  you need to reduce an RGB file to a paletted file, or if a paletted
2118       file has more entries then will fit on  your  screen,  png_set_dither()
2119       will  do  that.   Note  that  this is a simple match dither that merely
2120       finds the closest color available.  This should work fairly  well  with
2121       optimized  palettes,  and fairly badly with linear color cubes.  If you
2122       pass a palette that is larger then maximum_colors, the file will reduce
2123       the number of colors in the palette so it will fit into maximum_colors.
2124       If there is a histogram, it  will  use  it  to  make  more  intelligent
2125       choices  when  reducing  the palette.  If there is no histogram, it may
2126       not do as good a job.
2127
2128          if (color_type & PNG_COLOR_MASK_COLOR)
2129          {
2130             if (png_get_valid(png_ptr, info_ptr,
2131                PNG_INFO_PLTE))
2132             {
2133                png_uint_16p histogram = NULL;
2134
2135                png_get_hIST(png_ptr, info_ptr,
2136                   &histogram);
2137                png_set_dither(png_ptr, palette, num_palette,
2138                   max_screen_colors, histogram, 1);
2139             }
2140             else
2141             {
2142                png_color std_color_cube[MAX_SCREEN_COLORS] =
2143                   { ... colors ... };
2144
2145                png_set_dither(png_ptr, std_color_cube,
2146                   MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
2147                   NULL,0);
2148             }
2149          }
2150
2151       PNG files describe monochrome as black being zero and white being  one.
2152       The  following  code  will reverse this (make black be one and white be
2153       zero):
2154
2155          if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
2156             png_set_invert_mono(png_ptr);
2157
2158       This function can also be  used  to  invert  grayscale  and  gray-alpha
2159       images:
2160
2161          if (color_type == PNG_COLOR_TYPE_GRAY ||
2162               color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
2163             png_set_invert_mono(png_ptr);
2164
2165       PNG  files  store  16 bit pixels in network byte order (big-endian, ie.
2166       most significant bits first).  This code changes  the  storage  to  the
2167       other  way  (little-endian,  i.e. least significant bits first, the way
2168       PCs store them):
2169
2170           if (bit_depth == 16)
2171               png_set_swap(png_ptr);
2172
2173       If you are using packed-pixel images (1, 2, or 4 bits/pixel),  and  you
2174       need to change the order the pixels are packed into bytes, you can use:
2175
2176           if (bit_depth < 8)
2177              png_set_packswap(png_ptr);
2178
2179       Finally,  you can write your own transformation function if none of the
2180       existing ones meets your needs.  This is done  by  setting  a  callback
2181       with
2182
2183           png_set_read_user_transform_fn(png_ptr,
2184              read_transform_fn);
2185
2186       You must supply the function
2187
2188           void read_transform_fn(png_ptr ptr, row_info_ptr
2189              row_info, png_bytep data)
2190
2191       See  pngtest.c  for  a  working  example.  Your function will be called
2192       after all of the other transformations have been processed.
2193
2194       You can also set up a pointer to a user structure for use by your call‐
2195       back  function,  and you can inform libpng that your transform function
2196       will change the number of channels or bit depth with the function
2197
2198           png_set_user_transform_info(png_ptr, user_ptr,
2199              user_depth, user_channels);
2200
2201       The user's application, not libpng, is responsible for  allocating  and
2202       freeing any memory required for the user structure.
2203
2204       You  can  retrieve  the  pointer  via  the function png_get_user_trans‐
2205       form_ptr().  For example:
2206
2207           voidp read_user_transform_ptr =
2208              png_get_user_transform_ptr(png_ptr);
2209
2210       The last thing to handle is interlacing;  this  is  covered  in  detail
2211       below, but you must call the function here if you want libpng to handle
2212       expansion of the interlaced image.
2213
2214           number_of_passes = png_set_interlace_handling(png_ptr);
2215
2216       After setting the transformations,  libpng  can  update  your  png_info
2217       structure  to  reflect  any  transformations you've requested with this
2218       call.  This is most useful to  update  the  info  structure's  rowbytes
2219       field  so  you can use it to allocate your image memory.  This function
2220       will also update your palette with the correct screen_gamma  and  back‐
2221       ground if these have been given with the calls above.
2222
2223           png_read_update_info(png_ptr, info_ptr);
2224
2225       After  you call png_read_update_info(), you can allocate any memory you
2226       need to hold the image.  The row data is simply raw byte data  for  all
2227       forms  of  images.  As the actual allocation varies among applications,
2228       no example will be given.  If you are allocating one large  chunk,  you
2229       will  need  to  build  an  array of pointers to each row, as it will be
2230       needed for some of the functions below.
2231
2232
2233   Reading image data
2234       After you've allocated memory, you can read the image data.   The  sim‐
2235       plest  way  to  do this is in one function call.  If you are allocating
2236       enough  memory  to  hold  the  whole   image,   you   can   just   call
2237       png_read_image()  and libpng will read in all the image data and put it
2238       in the memory area supplied.  You will need to  pass  in  an  array  of
2239       pointers to each row.
2240
2241       This  function  automatically handles interlacing, so you don't need to
2242       call png_set_interlace_handling() or call this function multiple times,
2243       or any of that other stuff necessary with png_read_rows().
2244
2245          png_read_image(png_ptr, row_pointers);
2246
2247       where row_pointers is:
2248
2249          png_bytep row_pointers[height];
2250
2251       You can point to void or char or whatever you use for pixels.
2252
2253       If  you  don't  want  to  read  in the whole image at once, you can use
2254       png_read_rows() instead.  If there  is  no  interlacing  (check  inter‐
2255       lace_type == PNG_INTERLACE_NONE), this is simple:
2256
2257           png_read_rows(png_ptr, row_pointers, NULL,
2258              number_of_rows);
2259
2260       where row_pointers is the same as in the png_read_image() call.
2261
2262       If  you  are  doing this just one row at a time, you can do this with a
2263       single row_pointer instead of an array of row_pointers:
2264
2265           png_bytep row_pointer = row;
2266           png_read_row(png_ptr, row_pointer, NULL);
2267
2268       If the file is interlaced (interlace_type !=  0  in  the  IHDR  chunk),
2269       things  get  somewhat harder.  The only current (PNG Specification ver‐
2270       sion 1.2) interlacing type for PNG  is  (interlace_type  ==  PNG_INTER‐
2271       LACE_ADAM7)  is  a  somewhat  complicated 2D interlace scheme, known as
2272       Adam7, that breaks down an image into seven smaller images  of  varying
2273       size, based on an 8x8 grid.
2274
2275       libpng  can  fill  out those images or it can give them to you "as is".
2276       If you want them filled out, there are two ways to do  that.   The  one
2277       mentioned  in  the  PNG  specification is to expand each pixel to cover
2278       those pixels that have not been  read  yet  (the  "rectangle"  method).
2279       This  results  in  a  blocky  image for the first pass, which gradually
2280       smooths out as more pixels are read.  The other method is the "sparkle"
2281       method,  where pixels are drawn only in their final locations, with the
2282       rest of the image remaining whatever colors they  were  initialized  to
2283       before  the  start of the read.  The first method usually looks better,
2284       but tends to be slower, as there are more pixels to put in the rows.
2285
2286       If you don't want libpng to handle the interlacing details,  just  call
2287       png_read_rows()  seven  times to read in all seven images.  Each of the
2288       images is a valid image by itself, or they can all be  combined  on  an
2289       8x8 grid to form a single image (although if you intend to combine them
2290       you would be far better off using the libpng interlace handling).
2291
2292       The first pass will return an image 1/8 as wide  as  the  entire  image
2293       (every 8th column starting in column 0) and 1/8 as high as the original
2294       (every 8th row starting in row 0), the  second  will  be  1/8  as  wide
2295       (starting  in  column 4) and 1/8 as high (also starting in row 0).  The
2296       third pass will be 1/4 as wide (every 4th pixel starting in  column  0)
2297       and  1/8 as high (every 8th row starting in row 4), and the fourth pass
2298       will be 1/4 as wide and 1/4 as high (every 4th column starting in  col‐
2299       umn  2,  and  every  4th  row  starting in row 0).  The fifth pass will
2300       return an image 1/2 as wide, and 1/4 as high (starting at column 0  and
2301       row 2), while the sixth pass will be 1/2 as wide and 1/2 as high as the
2302       original (starting in column 1 and row 0).  The seventh and final  pass
2303       will be as wide as the original, and 1/2 as high, containing all of the
2304       odd numbered scanlines.  Phew!
2305
2306       If you want libpng to expand  the  images,  call  this  before  calling
2307       png_start_read_image() or png_read_update_info():
2308
2309           if (interlace_type == PNG_INTERLACE_ADAM7)
2310               number_of_passes
2311                  = png_set_interlace_handling(png_ptr);
2312
2313       This  will  return  the  number  of  passes needed.  Currently, this is
2314       seven, but may change if another interlace type is added.   This  func‐
2315       tion  can  be  called even if the file is not interlaced, where it will
2316       return one pass.
2317
2318       If you are not going to display the image  after  each  pass,  but  are
2319       going  to  wait  until  the  entire  image  is read in, use the sparkle
2320       effect.  This effect is faster and the end result of either  method  is
2321       exactly  the  same.   If you are planning on displaying the image after
2322       each pass, the "rectangle" effect is generally  considered  the  better
2323       looking one.
2324
2325       If  you  only  want  the "sparkle" effect, just call png_read_rows() as
2326       normal, with the third parameter NULL.  Make sure you  make  pass  over
2327       the  image number_of_passes times, and you don't change the data in the
2328       rows between calls.  You can change the locations of the data, just not
2329       the  data.  Each pass only writes the pixels appropriate for that pass,
2330       and assumes the data from previous passes is still valid.
2331
2332           png_read_rows(png_ptr, row_pointers, NULL,
2333              number_of_rows);
2334
2335       If you only want the first effect (the  rectangles),  do  the  same  as
2336       before except pass the row buffer in the third parameter, and leave the
2337       second parameter NULL.
2338
2339           png_read_rows(png_ptr, NULL, row_pointers,
2340              number_of_rows);
2341
2342
2343   Finishing a sequential read
2344       After you are finished reading the image through the  low-level  inter‐
2345       face,  you  can finish reading the file.  If you are interested in com‐
2346       ments or time, which may be stored either before  or  after  the  image
2347       data,  you should pass the separate png_info struct if you want to keep
2348       the comments from before and after the image separate.  If you are  not
2349       interested, you can pass NULL.
2350
2351          png_read_end(png_ptr, end_info);
2352
2353       When  you  are  done,  you can free all memory allocated by libpng like
2354       this:
2355
2356          png_destroy_read_struct(&png_ptr, &info_ptr,
2357              &end_info);
2358
2359       It is also possible to individually  free  the  info_ptr  members  that
2360       point to libpng-allocated storage with the following function:
2361
2362           png_free_data(png_ptr, info_ptr, mask, seq)
2363           mask - identifies data to be freed, a mask
2364                  containing the bitwise OR of one or
2365                  more of
2366                    PNG_FREE_PLTE, PNG_FREE_TRNS,
2367                    PNG_FREE_HIST, PNG_FREE_ICCP,
2368                    PNG_FREE_PCAL, PNG_FREE_ROWS,
2369                    PNG_FREE_SCAL, PNG_FREE_SPLT,
2370                    PNG_FREE_TEXT, PNG_FREE_UNKN,
2371                  or simply PNG_FREE_ALL
2372           seq  - sequence number of item to be freed
2373                  (-1 for all items)
2374
2375       This  function  may  be  safely  called  when  the relevant storage has
2376       already been freed, or has not yet been allocated, or was allocated  by
2377       the  user  and not by libpng,  and will in those cases do nothing.  The
2378       "seq" parameter is ignored if only one item of the selected data  type,
2379       such  as  PLTE, is allowed.  If "seq" is not -1, and multiple items are
2380       allowed for the data type identified in the mask, such as text or sPLT,
2381       only the n'th item in the structure is freed, where n is "seq".
2382
2383       The default behavior is only to free data that was allocated internally
2384       by libpng.  This can be changed, so that libpng will not free the data,
2385       or  so  that  it  will  free  data  that was allocated by the user with
2386       png_malloc() or png_zalloc() and passed in via a png_set_*()  function,
2387       with
2388
2389           png_data_freer(png_ptr, info_ptr, freer, mask)
2390           mask   - which data elements are affected
2391                    same choices as in png_free_data()
2392           freer  - one of
2393                      PNG_DESTROY_WILL_FREE_DATA
2394                      PNG_SET_WILL_FREE_DATA
2395                      PNG_USER_WILL_FREE_DATA
2396
2397       This  function  only affects data that has already been allocated.  You
2398       can call this function after reading the PNG data  but  before  calling
2399       any   png_set_*()  functions,  to  control  whether  the  user  or  the
2400       png_set_*() function is responsible for freeing any existing data  that
2401       might  be present, and again after the png_set_*() functions to control
2402       whether the user or png_destroy_*() is supposed to free the data.  When
2403       the user assumes responsibility for libpng-allocated data, the applica‐
2404       tion must use png_free() to  free  it,  and  when  the  user  transfers
2405       responsibility to libpng for data that the user has allocated, the user
2406       must have used png_malloc() or png_zalloc() to allocate it.
2407
2408       If you allocated your row_pointers in  a  single  block,  as  suggested
2409       above in the description of the high level read interface, you must not
2410       transfer  responsibility  for  freeing  it  to  the   png_set_rows   or
2411       png_read_destroy  function,  because  they  would  also try to free the
2412       individual row_pointers[i].
2413
2414       If you  allocated  text_ptr.text,  text_ptr.lang,  and  text_ptr.trans‐
2415       lated_keyword  separately,  do  not transfer responsibility for freeing
2416       text_ptr to libpng, because when libpng fills a png_text  structure  it
2417       combines  these  members  with the key member, and png_free_data() will
2418       free only text_ptr.key.  Similarly, if you transfer responsibility  for
2419       free'ing  text_ptr  from  libpng  to your application, your application
2420       must not separately free those members.
2421
2422       The png_free_data() function will turn off the "valid"  flag  for  any‐
2423       thing  it frees.  If you need to turn the flag off for a chunk that was
2424       freed by your application instead of by libpng, you can use
2425
2426           png_set_invalid(png_ptr, info_ptr, mask);
2427           mask - identifies the chunks to be made invalid,
2428                  containing the bitwise OR of one or
2429                  more of
2430                    PNG_INFO_gAMA, PNG_INFO_sBIT,
2431                    PNG_INFO_cHRM, PNG_INFO_PLTE,
2432                    PNG_INFO_tRNS, PNG_INFO_bKGD,
2433                    PNG_INFO_hIST, PNG_INFO_pHYs,
2434                    PNG_INFO_oFFs, PNG_INFO_tIME,
2435                    PNG_INFO_pCAL, PNG_INFO_sRGB,
2436                    PNG_INFO_iCCP, PNG_INFO_sPLT,
2437                    PNG_INFO_sCAL, PNG_INFO_IDAT
2438
2439       For a more compact example of reading a PNG image, see the  file  exam‐
2440       ple.c.
2441
2442
2443   Reading PNG files progressively
2444       The  progressive  reader is slightly different then the non-progressive
2445       reader.   Instead  of  calling  png_read_info(),  png_read_rows(),  and
2446       png_read_end(),  you  make  one call to png_process_data(), which calls
2447       callbacks when it has the info, a row, or the end of  the  image.   You
2448       set  up  these callbacks with png_set_progressive_read_fn().  You don't
2449       have to worry about the input/output functions of libpng,  as  you  are
2450       giving  the  library  the  data directly in png_process_data().  I will
2451       assume that you have read the section on reading PNG files above, so  I
2452       will  only  highlight  the differences (although I will show all of the
2453       code).
2454
2455       png_structp png_ptr; png_infop info_ptr;
2456
2457        /*  An example code fragment of how you would
2458            initialize the progressive reader in your
2459            application. */
2460        int
2461        initialize_png_reader()
2462        {
2463           png_ptr = png_create_read_struct
2464               (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2465                user_error_fn, user_warning_fn);
2466           if (!png_ptr)
2467               return (ERROR);
2468           info_ptr = png_create_info_struct(png_ptr);
2469           if (!info_ptr)
2470           {
2471               png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
2472                  (png_infopp)NULL);
2473               return (ERROR);
2474           }
2475
2476           if (setjmp(png_jmpbuf(png_ptr)))
2477           {
2478               png_destroy_read_struct(&png_ptr, &info_ptr,
2479                  (png_infopp)NULL);
2480               return (ERROR);
2481           }
2482
2483           /* This one's new.  You can provide functions
2484              to be called when the header info is valid,
2485              when each row is completed, and when the image
2486              is finished.  If you aren't using all functions,
2487              you can specify NULL parameters.  Even when all
2488              three functions are NULL, you need to call
2489              png_set_progressive_read_fn().  You can use
2490              any struct as the user_ptr (cast to a void pointer
2491              for the function call), and retrieve the pointer
2492              from inside the callbacks using the function
2493
2494                 png_get_progressive_ptr(png_ptr);
2495
2496              which will return a void pointer, which you have
2497              to cast appropriately.
2498            */
2499           png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2500               info_callback, row_callback, end_callback);
2501
2502           return 0;
2503        }
2504
2505        /* A code fragment that you call as you receive blocks
2506          of data */
2507        int
2508        process_data(png_bytep buffer, png_uint_32 length)
2509        {
2510           if (setjmp(png_jmpbuf(png_ptr)))
2511           {
2512               png_destroy_read_struct(&png_ptr, &info_ptr,
2513                  (png_infopp)NULL);
2514               return (ERROR);
2515           }
2516
2517           /* This one's new also.  Simply give it a chunk
2518              of data from the file stream (in order, of
2519              course).  On machines with segmented memory
2520              models machines, don't give it any more than
2521              64K.  The library seems to run fine with sizes
2522              of 4K. Although you can give it much less if
2523              necessary (I assume you can give it chunks of
2524              1 byte, I haven't tried less then 256 bytes
2525              yet).  When this function returns, you may
2526              want to display any rows that were generated
2527              in the row callback if you don't already do
2528              so there.
2529            */
2530           png_process_data(png_ptr, info_ptr, buffer, length);
2531           return 0;
2532        }
2533
2534        /* This function is called (as set by
2535           png_set_progressive_read_fn() above) when enough data
2536           has been supplied so all of the header has been
2537           read.
2538        */
2539        void
2540        info_callback(png_structp png_ptr, png_infop info)
2541        {
2542           /* Do any setup here, including setting any of
2543              the transformations mentioned in the Reading
2544              PNG files section.  For now, you _must_ call
2545              either png_start_read_image() or
2546              png_read_update_info() after all the
2547              transformations are set (even if you don't set
2548              any).  You may start getting rows before
2549              png_process_data() returns, so this is your
2550              last chance to prepare for that.
2551            */
2552        }
2553
2554        /* This function is called when each row of image
2555           data is complete */
2556        void
2557        row_callback(png_structp png_ptr, png_bytep new_row,
2558           png_uint_32 row_num, int pass)
2559        {
2560           /* If the image is interlaced, and you turned
2561              on the interlace handler, this function will
2562              be called for every row in every pass.  Some
2563              of these rows will not be changed from the
2564              previous pass.  When the row is not changed,
2565              the new_row variable will be NULL.  The rows
2566              and passes are called in order, so you don't
2567              really need the row_num and pass, but I'm
2568              supplying them because it may make your life
2569              easier.
2570
2571              For the non-NULL rows of interlaced images,
2572              you must call png_progressive_combine_row()
2573              passing in the row and the old row.  You can
2574              call this function for NULL rows (it will just
2575              return) and for non-interlaced images (it just
2576              does the memcpy for you) if it will make the
2577              code easier.  Thus, you can just do this for
2578              all cases:
2579            */
2580
2581               png_progressive_combine_row(png_ptr, old_row,
2582                 new_row);
2583
2584           /* where old_row is what was displayed for
2585              previously for the row.  Note that the first
2586              pass (pass == 0, really) will completely cover
2587              the old row, so the rows do not have to be
2588              initialized.  After the first pass (and only
2589              for interlaced images), you will have to pass
2590              the current row, and the function will combine
2591              the old row and the new row.
2592           */
2593        }
2594
2595        void
2596        end_callback(png_structp png_ptr, png_infop info)
2597        {
2598           /* This function is called after the whole image
2599              has been read, including any chunks after the
2600              image (up to and including the IEND).  You
2601              will usually have the same info chunk as you
2602              had in the header, although some data may have
2603              been added to the comments and time fields.
2604
2605              Most people won't do much here, perhaps setting
2606              a flag that marks the image as finished.
2607            */
2608        }
2609
2610
2611
2612

IV. Writing

2614       Much of this is very similar to reading.  However, everything of impor‐
2615       tance is repeated here, so you won't have to constantly look back up in
2616       the reading section to understand writing.
2617
2618
2619   Setup
2620       You will want to do the I/O initialization before you get into  libpng,
2621       so  if it doesn't work, you don't have anything to undo. If you are not
2622       using the standard I/O functions, you will need to  replace  them  with
2623       custom writing functions.  See the discussion under Customizing libpng.
2624
2625           FILE *fp = fopen(file_name, "wb");
2626           if (!fp)
2627           {
2628              return (ERROR);
2629           }
2630
2631       Next, png_struct and png_info need to be allocated and initialized.  As
2632       these can be both relatively large, you may not want to store these  on
2633       the  stack,  unless you have stack space to spare.  Of course, you will
2634       want to check if they return NULL.  If you are also reading, you  won't
2635       want  to  name  your  read  structure  and  your  write  structure both
2636       "png_ptr"; you can call them anything you like, such as "read_ptr"  and
2637       "write_ptr".  Look at pngtest.c, for example.
2638
2639           png_structp png_ptr = png_create_write_struct
2640              (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2641               user_error_fn, user_warning_fn);
2642           if (!png_ptr)
2643              return (ERROR);
2644
2645           png_infop info_ptr = png_create_info_struct(png_ptr);
2646           if (!info_ptr)
2647           {
2648              png_destroy_write_struct(&png_ptr,
2649                (png_infopp)NULL);
2650              return (ERROR);
2651           }
2652
2653       If  you  want  to  use  your  own  memory  allocation  routines, define
2654       PNG_USER_MEM_SUPPORTED and use png_create_write_struct_2()  instead  of
2655       png_create_write_struct():
2656
2657           png_structp png_ptr = png_create_write_struct_2
2658              (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2659               user_error_fn, user_warning_fn, (png_voidp)
2660               user_mem_ptr, user_malloc_fn, user_free_fn);
2661
2662       After you have these structures, you will need to set up the error han‐
2663       dling.  When libpng encounters an error, it expects to  longjmp()  back
2664       to  your  routine.   Therefore, you will need to call setjmp() and pass
2665       the png_jmpbuf(png_ptr).  If you write the  file  from  different  rou‐
2666       tines,  you  will need to update the png_jmpbuf(png_ptr) every time you
2667       enter a new routine that will call a png_*() function.  See your  docu‐
2668       mentation  of  setjmp/longjmp for your compiler for more information on
2669       setjmp/longjmp.  See the discussion on libpng  error  handling  in  the
2670       Customizing  Libpng  section  below  for more information on the libpng
2671       error handling.
2672
2673           if (setjmp(png_jmpbuf(png_ptr)))
2674           {
2675              png_destroy_write_struct(&png_ptr, &info_ptr);
2676              fclose(fp);
2677              return (ERROR);
2678           }
2679           ...
2680           return;
2681
2682       If you would rather avoid the complexity of setjmp/longjmp issues,  you
2683       can  compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case errors
2684       will result in a call to PNG_ABORT() which defaults to abort().
2685
2686       Now you need to set up the output code.  The default for libpng  is  to
2687       use  the C function fwrite().  If you use this, you will need to pass a
2688       valid FILE * in the function png_init_io().  Be sure that the  file  is
2689       opened  in  binary  mode.  Again, if you wish to handle writing data in
2690       another way, see the discussion on libpng I/O handling in the Customiz‐
2691       ing Libpng section below.
2692
2693           png_init_io(png_ptr, fp);
2694
2695       If  you are embedding your PNG into a datastream such as MNG, and don't
2696       want libpng to write the 8-byte signature, or if you have already writ‐
2697       ten the signature in your application, use
2698
2699           png_set_sig_bytes(png_ptr, 8);
2700
2701       to inform libpng that it should not write a signature.
2702
2703
2704   Write callbacks
2705       At  this  point, you can set up a callback function that will be called
2706       after each row has been  written,  which  you  can  use  to  control  a
2707       progress  meter or the like.  It's demonstrated in pngtest.c.  You must
2708       supply a function
2709
2710           void write_row_callback(png_ptr, png_uint_32 row,
2711              int pass);
2712           {
2713             /* put your code here */
2714           }
2715
2716       (You can give it another name that you like instead of "write_row_call‐
2717       back")
2718
2719       To inform libpng about your function, use
2720
2721           png_set_write_status_fn(png_ptr, write_row_callback);
2722
2723       You  now  have the option of modifying how the compression library will
2724       run.  The following functions are mainly for testing, but may be useful
2725       in  some  cases, like if you need to write PNG files extremely fast and
2726       are willing to give up some compression, or if you want to get the max‐
2727       imum  possible  compression  at  the expense of slower writing.  If you
2728       have no special needs in this area, let the library do what it wants by
2729       not  calling  this  function  at all, as it has been tuned to deliver a
2730       good speed/compression ratio. The second parameter to  png_set_filter()
2731       is  the filter method, for which the only valid values are 0 (as of the
2732       July 1999 PNG specification, version 1.2) or 64 (if you are  writing  a
2733       PNG  datastream that is to be embedded in a MNG datastream).  The third
2734       parameter is a flag that indicates  which  filter  type(s)  are  to  be
2735       tested for each scanline.  See the PNG specification for details on the
2736       specific filter types.
2737
2738
2739           /* turn on or off filtering, and/or choose
2740              specific filters.  You can use either a single
2741              PNG_FILTER_VALUE_NAME or the bitwise OR of one
2742              or more PNG_FILTER_NAME masks. */
2743           png_set_filter(png_ptr, 0,
2744              PNG_FILTER_NONE  | PNG_FILTER_VALUE_NONE |
2745              PNG_FILTER_SUB   | PNG_FILTER_VALUE_SUB  |
2746              PNG_FILTER_UP    | PNG_FILTER_VALUE_UP   |
2747              PNG_FILTER_AVG   | PNG_FILTER_VALUE_AVG  |
2748              PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2749              PNG_ALL_FILTERS);
2750
2751       If an application wants to start and stop using particular filters dur‐
2752       ing compression, it should start out with all of the filters (to ensure
2753       that the previous row of pixels will be  stored  in  case  it's  needed
2754       later), and then add and remove them after the start of compression.
2755
2756       If  you  are  writing  a PNG datastream that is to be embedded in a MNG
2757       datastream, the second parameter can be either 0 or 64.
2758
2759       The png_set_compression_*() functions interface to the zlib compression
2760       library,  and  should mostly be ignored unless you really know what you
2761       are  doing.   The  only  generally  useful  call  is   png_set_compres‐
2762       sion_level()  which changes how much time zlib spends on trying to com‐
2763       press the image data.  See the Compression Library  (zlib.h  and  algo‐
2764       rithm.txt,  distributed  with zlib) for details on the compression lev‐
2765       els.
2766
2767           /* set the zlib compression level */
2768           png_set_compression_level(png_ptr,
2769               Z_BEST_COMPRESSION);
2770
2771           /* set other zlib parameters */
2772           png_set_compression_mem_level(png_ptr, 8);
2773           png_set_compression_strategy(png_ptr,
2774               Z_DEFAULT_STRATEGY);
2775           png_set_compression_window_bits(png_ptr, 15);
2776           png_set_compression_method(png_ptr, 8);
2777           png_set_compression_buffer_size(png_ptr, 8192)
2778
2779       extern PNG_EXPORT(void,png_set_zbuf_size)
2780
2781
2782   Setting the contents of info for output
2783       You now need to fill in the png_info structure with all  the  data  you
2784       wish  to  write  before the actual image.  Note that the only thing you
2785       are allowed to write after the image is the text chunks  and  the  time
2786       chunk  (as  of PNG Specification 1.2, anyway).  See png_write_end() and
2787       the latest PNG specification for more information on that.  If you wish
2788       to write them before the image, fill them in now, and flag that data as
2789       being valid.  If you want to wait until after the data, don't fill them
2790       until  png_write_end().   For all the fields in png_info and their data
2791       types, see png.h.  For explanations of what the fields contain, see the
2792       PNG specification.
2793
2794       Some of the more important parts of the png_info are:
2795
2796           png_set_IHDR(png_ptr, info_ptr, width, height,
2797              bit_depth, color_type, interlace_type,
2798              compression_type, filter_method)
2799           width          - holds the width of the image
2800                            in pixels (up to 2^31).
2801           height         - holds the height of the image
2802                            in pixels (up to 2^31).
2803           bit_depth      - holds the bit depth of one of the
2804                            image channels.
2805                            (valid values are 1, 2, 4, 8, 16
2806                            and depend also on the
2807                            color_type.  See also significant
2808                            bits (sBIT) below).
2809           color_type     - describes which color/alpha
2810                            channels are present.
2811                            PNG_COLOR_TYPE_GRAY
2812                               (bit depths 1, 2, 4, 8, 16)
2813                            PNG_COLOR_TYPE_GRAY_ALPHA
2814                               (bit depths 8, 16)
2815                            PNG_COLOR_TYPE_PALETTE
2816                               (bit depths 1, 2, 4, 8)
2817                            PNG_COLOR_TYPE_RGB
2818                               (bit_depths 8, 16)
2819                            PNG_COLOR_TYPE_RGB_ALPHA
2820                               (bit_depths 8, 16)
2821
2822                            PNG_COLOR_MASK_PALETTE
2823                            PNG_COLOR_MASK_COLOR
2824                            PNG_COLOR_MASK_ALPHA
2825
2826           interlace_type - PNG_INTERLACE_NONE or
2827                            PNG_INTERLACE_ADAM7
2828           compression_type - (must be
2829                            PNG_COMPRESSION_TYPE_DEFAULT)
2830           filter_method  - (must be PNG_FILTER_TYPE_DEFAULT
2831                            or, if you are writing a PNG to
2832                            be embedded in a MNG datastream,
2833                            can also be
2834                            PNG_INTRAPIXEL_DIFFERENCING)
2835
2836       If  you  call  png_set_IHDR(),  the  call must appear before any of the
2837       other png_set_*() functions, because they might require access to  some
2838       of  the  IHDR  settings.   The  remaining  png_set_*() functions can be
2839       called in any order.
2840
2841       If you wish, you can reset  the  compression_type,  interlace_type,  or
2842       filter_method  later  by  calling png_set_IHDR() again; if you do this,
2843       the width, height, bit_depth, and color_type must be the same  in  each
2844       call.
2845
2846           png_set_PLTE(png_ptr, info_ptr, palette,
2847              num_palette);
2848           palette        - the palette for the file
2849                            (array of png_color)
2850           num_palette    - number of entries in the palette
2851
2852           png_set_gAMA(png_ptr, info_ptr, gamma);
2853           gamma          - the gamma the image was created
2854                            at (PNG_INFO_gAMA)
2855
2856           png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2857           srgb_intent    - the rendering intent
2858                            (PNG_INFO_sRGB) The presence of
2859                            the sRGB chunk means that the pixel
2860                            data is in the sRGB color space.
2861                            This chunk also implies specific
2862                            values of gAMA and cHRM.  Rendering
2863                            intent is the CSS-1 property that
2864                            has been defined by the International
2865                            Color Consortium
2866                            (http://www.color.org).
2867                            It can be one of
2868                            PNG_sRGB_INTENT_SATURATION,
2869                            PNG_sRGB_INTENT_PERCEPTUAL,
2870                            PNG_sRGB_INTENT_ABSOLUTE, or
2871                            PNG_sRGB_INTENT_RELATIVE.
2872
2873
2874           png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2875              srgb_intent);
2876           srgb_intent    - the rendering intent
2877                            (PNG_INFO_sRGB) The presence of the
2878                            sRGB chunk means that the pixel
2879                            data is in the sRGB color space.
2880                            This function also causes gAMA and
2881                            cHRM chunks with the specific values
2882                            that are consistent with sRGB to be
2883                            written.
2884
2885           png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2886                             profile, proflen);
2887           name            - The profile name.
2888           compression     - The compression type; always
2889                             PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2890                             You may give NULL to this argument to
2891                             ignore it.
2892           profile         - International Color Consortium color
2893                             profile data. May contain NULs.
2894           proflen         - length of profile data in bytes.
2895
2896           png_set_sBIT(png_ptr, info_ptr, sig_bit);
2897           sig_bit        - the number of significant bits for
2898                            (PNG_INFO_sBIT) each of the gray, red,
2899                            green, and blue channels, whichever are
2900                            appropriate for the given color type
2901                            (png_color_16)
2902
2903           png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2904              trans_values);
2905           trans          - array of transparent
2906                            entries for palette (PNG_INFO_tRNS)
2907           trans_values   - graylevel or color sample values
2908                            (in order red, green, blue) of the
2909                            single transparent color for
2910                            non-paletted images (PNG_INFO_tRNS)
2911           num_trans      - number of transparent entries
2912                            (PNG_INFO_tRNS)
2913
2914           png_set_hIST(png_ptr, info_ptr, hist);
2915                           (PNG_INFO_hIST)
2916           hist           - histogram of palette (array of
2917                            png_uint_16)
2918
2919           png_set_tIME(png_ptr, info_ptr, mod_time);
2920           mod_time       - time image was last modified
2921                            (PNG_VALID_tIME)
2922
2923           png_set_bKGD(png_ptr, info_ptr, background);
2924           background     - background color (PNG_VALID_bKGD)
2925
2926           png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2927           text_ptr       - array of png_text holding image
2928                            comments
2929           text_ptr[i].compression - type of compression used
2930                        on "text" PNG_TEXT_COMPRESSION_NONE
2931                                  PNG_TEXT_COMPRESSION_zTXt
2932                                  PNG_ITXT_COMPRESSION_NONE
2933                                  PNG_ITXT_COMPRESSION_zTXt
2934           text_ptr[i].key   - keyword for comment.  Must contain
2935                        1-79 characters.
2936           text_ptr[i].text  - text comments for current
2937                                keyword.  Can be NULL or empty.
2938           text_ptr[i].text_length - length of text string,
2939                        after decompression, 0 for iTXt
2940           text_ptr[i].itxt_length - length of itxt string,
2941                        after decompression, 0 for tEXt/zTXt
2942           text_ptr[i].lang  - language of comment (NULL or
2943                                empty for unknown).
2944           text_ptr[i].translated_keyword  - keyword in UTF-8 (NULL
2945                                or empty for unknown).
2946           Note that the itxt_length, lang, and lang_key
2947           members of the text_ptr structure only exist
2948           when the library is built with iTXt chunk support.
2949
2950           num_text       - number of comments
2951
2952           png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2953              num_spalettes);
2954           palette_ptr    - array of png_sPLT_struct structures
2955                            to be added to the list of palettes
2956                            in the info structure.
2957           num_spalettes  - number of palette structures to be
2958                            added.
2959
2960           png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2961               unit_type);
2962           offset_x  - positive offset from the left
2963                            edge of the screen
2964           offset_y  - positive offset from the top
2965                            edge of the screen
2966           unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2967
2968           png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2969               unit_type);
2970           res_x       - pixels/unit physical resolution
2971                         in x direction
2972           res_y       - pixels/unit physical resolution
2973                         in y direction
2974           unit_type   - PNG_RESOLUTION_UNKNOWN,
2975                         PNG_RESOLUTION_METER
2976
2977           png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2978           unit        - physical scale units (an integer)
2979           width       - width of a pixel in physical scale units
2980           height      - height of a pixel in physical scale units
2981                         (width and height are doubles)
2982
2983           png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2984           unit        - physical scale units (an integer)
2985           width       - width of a pixel in physical scale units
2986           height      - height of a pixel in physical scale units
2987                        (width and height are strings like "2.54")
2988
2989           png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2990              num_unknowns)
2991           unknowns          - array of png_unknown_chunk
2992                               structures holding unknown chunks
2993           unknowns[i].name  - name of unknown chunk
2994           unknowns[i].data  - data of unknown chunk
2995           unknowns[i].size  - size of unknown chunk's data
2996           unknowns[i].location - position to write chunk in file
2997                                  0: do not write chunk
2998                                  PNG_HAVE_IHDR: before PLTE
2999                                  PNG_HAVE_PLTE: before IDAT
3000                                  PNG_AFTER_IDAT: after IDAT
3001
3002       The  "location"  member  is set automatically according to what part of
3003       the output file has already been written.  You  can  change  its  value
3004       after  calling  png_set_unknown_chunks()  as demonstrated in pngtest.c.
3005       Within each of the "locations", the chunks are sequenced  according  to
3006       their  position  in  the structure (that is, the value of "i", which is
3007       the order in which the chunk was either read from  the  input  file  or
3008       defined with png_set_unknown_chunks).
3009
3010       A  quick  word  about  text and num_text.  text is an array of png_text
3011       structures.  num_text is the number of valid structures in  the  array.
3012       Each png_text structure holds a language code, a keyword, a text value,
3013       and a compression type.
3014
3015       The compression types have the same valid numbers  as  the  compression
3016       types  of  the  image  data.  Currently, the only valid number is zero.
3017       However, you can store text either compressed or  uncompressed,  unlike
3018       images,  which  always have to be compressed.  So if you don't want the
3019       text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
3020       Because  tEXt and zTXt chunks don't have a language field, if you spec‐
3021       ify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt any language
3022       code or translated keyword will not be written out.
3023
3024       Until  text  gets  around  1000  bytes, it is not worth compressing it.
3025       After the text has been written out to the file, the  compression  type
3026       is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
3027       so that it isn't written out again at the end (in case you are  calling
3028       png_write_end() with the same struct.
3029
3030       The keywords that are given in the PNG Specification are:
3031
3032           Title            Short (one line) title or
3033                            caption for image
3034           Author           Name of image's creator
3035           Description      Description of image (possibly long)
3036           Copyright        Copyright notice
3037           Creation Time    Time of original image creation
3038                            (usually RFC 1123 format, see below)
3039           Software         Software used to create the image
3040           Disclaimer       Legal disclaimer
3041           Warning          Warning of nature of content
3042           Source           Device used to create the image
3043           Comment          Miscellaneous comment; conversion
3044                            from other image format
3045
3046       The keyword-text pairs work like this.  Keywords should be short simple
3047       descriptions of what the comment is about.  Some typical  keywords  are
3048       found in the PNG specification, as is some recommendations on keywords.
3049       You can repeat keywords in a file.  You can even write some text before
3050       the  image and some after.  For example, you may want to put a descrip‐
3051       tion of the image before the image,  but  leave  the  disclaimer  until
3052       after, so viewers working over modem connections don't have to wait for
3053       the disclaimer to go over the modem before they start seeing the image.
3054       Finally,  keywords  should  be full words, not abbreviations.  Keywords
3055       and text are in the ISO 8859-1 (Latin-1) character set (a  superset  of
3056       regular  ASCII) and can not contain NUL characters, and should not con‐
3057       tain control or other unprintable characters.   To  make  the  comments
3058       widely  readable,  stick  with  basic ASCII, and avoid machine specific
3059       character set extensions like the IBM-PC character  set.   The  keyword
3060       must  be  present,  but  you  can leave off the text string on non-com‐
3061       pressed pairs.  Compressed pairs must have a text string, as  only  the
3062       text  string is compressed anyway, so the compression would be meaning‐
3063       less.
3064
3065       PNG supports modification time via the png_time structure.  Two conver‐
3066       sion  routines  are  provided, png_convert_from_time_t() for time_t and
3067       png_convert_from_struct_tm() for struct tm.  The  time_t  routine  uses
3068       gmtime().   You  don't  have to use either of these, but if you wish to
3069       fill in the png_time structure directly, you should provide the time in
3070       universal time (GMT) if possible instead of your local time.  Note that
3071       the year number is the full year (e.g. 1998, rather than 98  -  PNG  is
3072       year 2000 compliant!), and that months start with 1.
3073
3074       If  you  want  to  store  the  time of the original image creation, you
3075       should use a plain tEXt chunk with the "Creation Time"  keyword.   This
3076       is  necessary  because  the  "creation time" of a PNG image is somewhat
3077       vague, depending on whether you mean the PNG file, the time  the  image
3078       was created in a non-PNG format, a still photo from which the image was
3079       scanned, or possibly the subject matter itself.  In order to facilitate
3080       machine-readable dates, it is recommended that the "Creation Time" tEXt
3081       chunk use RFC 1123 format dates (e.g.  "22  May  1997  18:07:10  GMT"),
3082       although  this  isn't  a requirement.  Unlike the tIME chunk, the "Cre‐
3083       ation Time" tEXt chunk is not expected to be automatically  changed  by
3084       the  software.   To  facilitate  the  use of RFC 1123 dates, a function
3085       png_convert_to_rfc1123(png_timep) is provided to convert from PNG  time
3086       to an RFC 1123 format string.
3087
3088
3089   Writing unknown chunks
3090       You  can use the png_set_unknown_chunks function to queue up chunks for
3091       writing.  You give it a chunk name, raw data, and a  size;  that's  all
3092       there  is  to  it.   The  chunks  will be written by the next following
3093       png_write_info_before_PLTE, png_write_info, or png_write_end  function.
3094       Any chunks previously read into the info structure's unknown-chunk list
3095       will also be written out in a sequence that satisfies the PNG  specifi‐
3096       cation's ordering rules.
3097
3098
3099   The high-level write interface
3100       At  this  point  there  are two ways to proceed; through the high-level
3101       write interface, or through a sequence of low-level  write  operations.
3102       You  can  use the high-level interface if your image data is present in
3103       the info structure.  All defined output transformations are  permitted,
3104       enabled by the following masks.
3105
3106           PNG_TRANSFORM_IDENTITY      No transformation
3107           PNG_TRANSFORM_PACKING       Pack 1, 2 and 4-bit samples
3108           PNG_TRANSFORM_PACKSWAP      Change order of packed
3109                                       pixels to LSB first
3110           PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
3111           PNG_TRANSFORM_SHIFT         Normalize pixels to the
3112                                       sBIT depth
3113           PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
3114                                       to BGRA
3115           PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
3116                                       to AG
3117           PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
3118                                       to transparency
3119           PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
3120           PNG_TRANSFORM_STRIP_FILLER        Strip out filler
3121                                             bytes (deprecated).
3122           PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
3123                                             filler bytes
3124           PNG_TRANSFORM_STRIP_FILLER_AFTER  Strip out trailing
3125                                             filler bytes
3126
3127       If  you  have  valid  image  data  in  the  info structure (you can use
3128       png_set_rows() to put image data in  the  info  structure),  simply  do
3129       this:
3130
3131           png_write_png(png_ptr, info_ptr, png_transforms, NULL)
3132
3133       where  png_transforms  is  an integer containing the bitwise OR of some
3134       set  of   transformation   flags.    This   call   is   equivalent   to
3135       png_write_info(),  followed the set of transformations indicated by the
3136       transform mask, then png_write_image(), and finally png_write_end().
3137
3138       (The final parameter of this call is not yet used.   Someday  it  might
3139       point  to  transformation  parameters  required  by  some future output
3140       transform.)
3141
3142       You must use png_transforms and not call any png_set_transform()  func‐
3143       tions when you use png_write_png().
3144
3145
3146   The low-level write interface
3147       If  you  are  going  the  low-level route instead, you are now ready to
3148       write all the file information up to the actual  image  data.   You  do
3149       this with a call to png_write_info().
3150
3151           png_write_info(png_ptr, info_ptr);
3152
3153       Note  that  there  is  one  transformation  you  may  need to do before
3154       png_write_info().  In PNG files, the alpha channel in an image  is  the
3155       level of opacity.  If your data is supplied as a level of transparency,
3156       you can invert the alpha channel before you write  it,  so  that  0  is
3157       fully  transparent  and  255 (in 8-bit or paletted images) or 65535 (in
3158       16-bit images) is fully opaque, with
3159
3160           png_set_invert_alpha(png_ptr);
3161
3162       This must appear before png_write_info()  instead  of  later  with  the
3163       other  transformations  because in the case of paletted images the tRNS
3164       chunk data has to be inverted before the tRNS  chunk  is  written.   If
3165       your  image is not a paletted image, the tRNS data (which in such cases
3166       represents a single color to be rendered as transparent) won't need  to
3167       be  changed,  and  you  can  safely  do  this transformation after your
3168       png_write_info() call.
3169
3170       If you need to write a private chunk that you want to appear before the
3171       PLTE  chunk  when  PLTE  is  present, you can write the PNG info in two
3172       steps, and insert code to write your own chunk between them:
3173
3174           png_write_info_before_PLTE(png_ptr, info_ptr);
3175           png_set_unknown_chunks(png_ptr, info_ptr, ...);
3176           png_write_info(png_ptr, info_ptr);
3177
3178       After you've written the file information, you can set up  the  library
3179       to  handle  any special transformations of the image data.  The various
3180       ways to transform the data will be described in  the  order  that  they
3181       should  occur.   This  is  important, as some of these change the color
3182       type and/or bit depth of the data, and some others only work on certain
3183       color  types and bit depths.  Even though each transformation checks to
3184       see if it has data that it can do something with, you should make  sure
3185       to  only enable a transformation if it will be valid for the data.  For
3186       example, don't swap red and blue on grayscale data.
3187
3188       PNG files store RGB pixels packed into 3 or 6 bytes.  This  code  tells
3189       the library to strip input data that has 4 or 8 bytes per pixel down to
3190       3 or 6 bytes (or strip 2 or 4-byte grayscale+filler  data  to  1  or  2
3191       bytes per pixel).
3192
3193           png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
3194
3195       where  the 0 is unused, and the location is either PNG_FILLER_BEFORE or
3196       PNG_FILLER_AFTER, depending upon whether the filler byte in  the  pixel
3197       is stored XRGB or RGBX.
3198
3199       PNG  files pack pixels of bit depths 1, 2, and 4 into bytes as small as
3200       they can, resulting in, for example, 8 pixels per byte for 1 bit files.
3201       If  the data is supplied at 1 pixel per byte, use this code, which will
3202       correctly pack the pixels into a single byte:
3203
3204           png_set_packing(png_ptr);
3205
3206       PNG files reduce possible bit depths to 1, 2, 4, 8, and  16.   If  your
3207       data is of another bit depth, you can write an sBIT chunk into the file
3208       so that decoders can recover the original data if desired.
3209
3210           /* Set the true bit depth of the image data */
3211           if (color_type & PNG_COLOR_MASK_COLOR)
3212           {
3213               sig_bit.red = true_bit_depth;
3214               sig_bit.green = true_bit_depth;
3215               sig_bit.blue = true_bit_depth;
3216           }
3217           else
3218           {
3219               sig_bit.gray = true_bit_depth;
3220           }
3221           if (color_type & PNG_COLOR_MASK_ALPHA)
3222           {
3223               sig_bit.alpha = true_bit_depth;
3224           }
3225
3226           png_set_sBIT(png_ptr, info_ptr, &sig_bit);
3227
3228       If the data is stored in the row buffer in a bit depth other  than  one
3229       supported  by  PNG  (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
3230       this will scale the values to appear to be the correct bit depth as  is
3231       required by PNG.
3232
3233           png_set_shift(png_ptr, &sig_bit);
3234
3235       PNG  files  store  16 bit pixels in network byte order (big-endian, ie.
3236       most significant bits first).  This code would be used if they are sup‐
3237       plied  the other way (little-endian, i.e. least significant bits first,
3238       the way PCs store them):
3239
3240           if (bit_depth > 8)
3241              png_set_swap(png_ptr);
3242
3243       If you are using packed-pixel images (1, 2, or 4 bits/pixel),  and  you
3244       need to change the order the pixels are packed into bytes, you can use:
3245
3246           if (bit_depth < 8)
3247              png_set_packswap(png_ptr);
3248
3249       PNG  files  store  3 color pixels in red, green, blue order.  This code
3250       would be used if they are supplied as blue, green, red:
3251
3252           png_set_bgr(png_ptr);
3253
3254       PNG files describe monochrome as black being zero and white being  one.
3255       This  code  would be used if the pixels are supplied with this reversed
3256       (black being one and white being zero):
3257
3258           png_set_invert_mono(png_ptr);
3259
3260       Finally, you can write your own transformation function if none of  the
3261       existing  ones  meets  your  needs.  This is done by setting a callback
3262       with
3263
3264           png_set_write_user_transform_fn(png_ptr,
3265              write_transform_fn);
3266
3267       You must supply the function
3268
3269           void write_transform_fn(png_ptr ptr, row_info_ptr
3270              row_info, png_bytep data)
3271
3272       See pngtest.c for a working example.   Your  function  will  be  called
3273       before any of the other transformations are processed.
3274
3275       You can also set up a pointer to a user structure for use by your call‐
3276       back function.
3277
3278           png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
3279
3280       The user_channels  and  user_depth  parameters  of  this  function  are
3281       ignored when writing; you can set them to zero as shown.
3282
3283       You  can  retrieve  the  pointer  via  the function png_get_user_trans‐
3284       form_ptr().  For example:
3285
3286           voidp write_user_transform_ptr =
3287              png_get_user_transform_ptr(png_ptr);
3288
3289       It is possible to have libpng flush any pending  output,  either  manu‐
3290       ally,  or automatically after a certain number of lines have been writ‐
3291       ten.  To flush the output stream a single time call:
3292
3293           png_write_flush(png_ptr);
3294
3295       and to have libpng flush the output stream periodically after a certain
3296       number of scanlines have been written, call:
3297
3298           png_set_flush(png_ptr, nrows);
3299
3300       Note   that   the   distance   between  rows  is  from  the  last  time
3301       png_write_flush() was called, or the first row of the image if  it  has
3302       never  been  called.   So if you write 50 lines, and then png_set_flush
3303       25, it will flush the output on the next scanline, and every  25  lines
3304       thereafter,  unless  png_write_flush()  is  called before 25 more lines
3305       have been written.  If nrows is too small (less than about 10 lines for
3306       a  640 pixel wide RGB image) the image compression may decrease notice‐
3307       ably (although this may  be  acceptable  for  real-time  applications).
3308       Infrequent  flushing will only degrade the compression performance by a
3309       few percent over images that do not use flushing.
3310
3311
3312   Writing the image data
3313       That's it for the transformations.  Now you can write the  image  data.
3314       The  simplest  way to do this is in one function call.  If you have the
3315       whole image in memory, you can just call png_write_image()  and  libpng
3316       will write the image.  You will need to pass in an array of pointers to
3317       each row.  This function  automatically  handles  interlacing,  so  you
3318       don't  need  to call png_set_interlace_handling() or call this function
3319       multiple  times,  or  any  of   that   other   stuff   necessary   with
3320       png_write_rows().
3321
3322           png_write_image(png_ptr, row_pointers);
3323
3324       where row_pointers is:
3325
3326           png_byte *row_pointers[height];
3327
3328       You can point to void or char or whatever you use for pixels.
3329
3330       If  you  don't  want  to  write  the  whole  image at once, you can use
3331       png_write_rows() instead.  If the file is not interlaced, this is  sim‐
3332       ple:
3333
3334           png_write_rows(png_ptr, row_pointers,
3335              number_of_rows);
3336
3337       row_pointers is the same as in the png_write_image() call.
3338
3339       If  you are just writing one row at a time, you can do this with a sin‐
3340       gle row_pointer instead of an array of row_pointers:
3341
3342           png_bytep row_pointer = row;
3343
3344           png_write_row(png_ptr, row_pointer);
3345
3346       When the file is interlaced, things can get a good  deal  more  compli‐
3347       cated.   The  only  currently (as of the PNG Specification version 1.2,
3348       dated July 1999) defined  interlacing  scheme  for  PNG  files  is  the
3349       "Adam7"  interlace scheme, that breaks down an image into seven smaller
3350       images of varying size.  libpng will build these images for you, or you
3351       can  do them yourself.  If you want to build them yourself, see the PNG
3352       specification for details of which pixels to write when.
3353
3354       If you don't want libpng to handle the interlacing  details,  just  use
3355       png_set_interlace_handling() and call png_write_rows() the correct num‐
3356       ber of times to write all seven sub-images.
3357
3358       If you want libpng to build the sub-images, call this before you  start
3359       writing any rows:
3360
3361           number_of_passes =
3362              png_set_interlace_handling(png_ptr);
3363
3364       This  will  return  the  number  of  passes needed.  Currently, this is
3365       seven, but may change if another interlace type is added.
3366
3367       Then write the complete image number_of_passes times.
3368
3369           png_write_rows(png_ptr, row_pointers,
3370              number_of_rows);
3371
3372       As some of these rows are not used, and thus  return  immediately,  you
3373       may  want  to read about interlacing in the PNG specification, and only
3374       update the rows that are actually used.
3375
3376
3377   Finishing a sequential write
3378       After you are finished writing the image, you should finish writing the
3379       file.   If  you  are interested in writing comments or time, you should
3380       pass an appropriately filled png_info pointer.  If you are  not  inter‐
3381       ested, you can pass NULL.
3382
3383           png_write_end(png_ptr, info_ptr);
3384
3385       When you are done, you can free all memory used by libpng like this:
3386
3387           png_destroy_write_struct(&png_ptr, &info_ptr);
3388
3389       It  is  also  possible  to  individually free the info_ptr members that
3390       point to libpng-allocated storage with the following function:
3391
3392           png_free_data(png_ptr, info_ptr, mask, seq)
3393           mask  - identifies data to be freed, a mask
3394                   containing the bitwise OR of one or
3395                   more of
3396                     PNG_FREE_PLTE, PNG_FREE_TRNS,
3397                     PNG_FREE_HIST, PNG_FREE_ICCP,
3398                     PNG_FREE_PCAL, PNG_FREE_ROWS,
3399                     PNG_FREE_SCAL, PNG_FREE_SPLT,
3400                     PNG_FREE_TEXT, PNG_FREE_UNKN,
3401                   or simply PNG_FREE_ALL
3402           seq   - sequence number of item to be freed
3403                   (-1 for all items)
3404
3405       This function may be  safely  called  when  the  relevant  storage  has
3406       already  been freed, or has not yet been allocated, or was allocated by
3407       the user  and not by libpng,  and will in those cases do nothing.   The
3408       "seq"  parameter is ignored if only one item of the selected data type,
3409       such as PLTE, is allowed.  If "seq" is not -1, and multiple  items  are
3410       allowed for the data type identified in the mask, such as text or sPLT,
3411       only the n'th item in the structure is freed, where n is "seq".
3412
3413       If you allocated data such as a palette that you passed  in  to  libpng
3414       with  png_set_*,  you  must  not  free it until just before the call to
3415       png_destroy_write_struct().
3416
3417       The default behavior is only to free data that was allocated internally
3418       by libpng.  This can be changed, so that libpng will not free the data,
3419       or so that it will free data  that  was  allocated  by  the  user  with
3420       png_malloc()  or png_zalloc() and passed in via a png_set_*() function,
3421       with
3422
3423           png_data_freer(png_ptr, info_ptr, freer, mask)
3424           mask   - which data elements are affected
3425                    same choices as in png_free_data()
3426           freer  - one of
3427                      PNG_DESTROY_WILL_FREE_DATA
3428                      PNG_SET_WILL_FREE_DATA
3429                      PNG_USER_WILL_FREE_DATA
3430
3431       For example, to transfer responsibility  for  some  data  from  a  read
3432       structure to a write structure, you could use
3433
3434           png_data_freer(read_ptr, read_info_ptr,
3435              PNG_USER_WILL_FREE_DATA,
3436              PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3437           png_data_freer(write_ptr, write_info_ptr,
3438              PNG_DESTROY_WILL_FREE_DATA,
3439              PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3440
3441       thereby  briefly reassigning responsibility for freeing to the user but
3442       immediately afterwards reassigning it once more  to  the  write_destroy
3443       function.   Having done this, it would then be safe to destroy the read
3444       structure and continue to use the PLTE, tRNS,  and  hIST  data  in  the
3445       write structure.
3446
3447       This  function  only affects data that has already been allocated.  You
3448       can call this function before calling after the  png_set_*()  functions
3449       to  control whether the user or png_destroy_*() is supposed to free the
3450       data.  When the user assumes responsibility for libpng-allocated  data,
3451       the  application  must  use  png_free()  to  free it, and when the user
3452       transfers responsibility to libpng for data that  the  user  has  allo‐
3453       cated, the user must have used png_malloc() or png_zalloc() to allocate
3454       it.
3455
3456       If you  allocated  text_ptr.text,  text_ptr.lang,  and  text_ptr.trans‐
3457       lated_keyword  separately,  do  not transfer responsibility for freeing
3458       text_ptr to libpng, because when libpng fills a png_text  structure  it
3459       combines  these  members  with the key member, and png_free_data() will
3460       free only text_ptr.key.  Similarly, if you transfer responsibility  for
3461       free'ing  text_ptr  from  libpng  to your application, your application
3462       must not separately free those members.  For a more compact example  of
3463       writing a PNG image, see the file example.c.
3464
3465

V. Modifying/Customizing libpng:

3467       There are two issues here.  The first is changing how libpng does stan‐
3468       dard things like memory allocation, input/output, and  error  handling.
3469       The  second  deals with more complicated things like adding new chunks,
3470       adding new transformations, and generally changing  how  libpng  works.
3471       Both  of  those  are  compile-time  issues; that is, they are generally
3472       determined at the time the code is written, and there is rarely a  need
3473       to provide the user with a means of changing them.
3474
3475       Memory allocation, input/output, and error handling
3476
3477       All  of  the  memory  allocation,  input/output,  and error handling in
3478       libpng goes through callbacks that are user-settable.  The default rou‐
3479       tines  are  in  pngmem.c,  pngrio.c,  pngwio.c, and pngerror.c, respec‐
3480       tively.  To change these functions, call the appropriate png_set_*_fn()
3481       function.
3482
3483       Memory  allocation is done through the functions png_malloc(), png_cal‐
3484       loc(), and png_free().  These currently just call the standard C  func‐
3485       tions.   png_calloc() calls png_malloc() and then png_memset() to clear
3486       the newly allocated memory to zero.  If your pointers can't access more
3487       then  64K  at a time, you will want to set MAXSEG_64K in zlib.h.  Since
3488       it is unlikely that the method of handling memory allocation on a plat‐
3489       form will change between applications, these functions must be modified
3490       in the library at compile time.  If  you  prefer  to  use  a  different
3491       method   of   allocating   and  freeing  data,  you  can  use  png_cre‐
3492       ate_read_struct_2() or png_create_write_struct_2() to register your own
3493       functions  as  described  above.   These  functions also provide a void
3494       pointer that can be retrieved via
3495
3496           mem_ptr=png_get_mem_ptr(png_ptr);
3497
3498       Your replacement memory functions must have prototypes as follows:
3499
3500           png_voidp malloc_fn(png_structp png_ptr,
3501              png_size_t size);
3502           void free_fn(png_structp png_ptr, png_voidp ptr);
3503
3504       Your malloc_fn() must return NULL in case of failure.  The png_malloc()
3505       function  will normally call png_error() if it receives a NULL from the
3506       system memory allocator or from your replacement malloc_fn().
3507
3508       Your free_fn() will never be called with a  NULL  ptr,  since  libpng's
3509       png_free() checks for NULL before calling free_fn().
3510
3511       Input/Output  in  libpng  is  done  through png_read() and png_write(),
3512       which currently just call fread() and fwrite().  The FILE *  is  stored
3513       in  png_struct  and  is  initialized via png_init_io().  If you wish to
3514       change the method of I/O, the library supplies callbacks that  you  can
3515       set  through  the  function png_set_read_fn() and png_set_write_fn() at
3516       run time, instead of calling the png_init_io() function.   These  func‐
3517       tions  also  provide a void pointer that can be retrieved via the func‐
3518       tion png_get_io_ptr().  For example:
3519
3520           png_set_read_fn(png_structp read_ptr,
3521               voidp read_io_ptr, png_rw_ptr read_data_fn)
3522
3523           png_set_write_fn(png_structp write_ptr,
3524               voidp write_io_ptr, png_rw_ptr write_data_fn,
3525               png_flush_ptr output_flush_fn);
3526
3527           voidp read_io_ptr = png_get_io_ptr(read_ptr);
3528           voidp write_io_ptr = png_get_io_ptr(write_ptr);
3529
3530       The replacement I/O functions must have prototypes as follows:
3531
3532           void user_read_data(png_structp png_ptr,
3533               png_bytep data, png_size_t length);
3534           void user_write_data(png_structp png_ptr,
3535               png_bytep data, png_size_t length);
3536           void user_flush_data(png_structp png_ptr);
3537
3538       The user_read_data() function is responsible for detecting and handling
3539       end-of-data errors.
3540
3541       Supplying  NULL  for the read, write, or flush functions sets them back
3542       to using the default C stream functions, which  expect  the  io_ptr  to
3543       point  to  a standard *FILE structure.  It is probably a mistake to use
3544       NULL for one of write_data_fn and output_flush_fn but not both of them,
3545       unless you have built libpng with PNG_NO_WRITE_FLUSH defined.  It is an
3546       error to read from a write stream, and vice versa.
3547
3548       Error handling in libpng is done through png_error() and png_warning().
3549       Errors  handled through png_error() are fatal, meaning that png_error()
3550       should never return to its caller.   Currently,  this  is  handled  via
3551       setjmp()   and   longjmp()   (unless  you  have  compiled  libpng  with
3552       PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
3553       but you could change this to do things like exit() if you should wish.
3554
3555       On  non-fatal  errors,  png_warning() is called to print a warning mes‐
3556       sage, and then  control  returns  to  the  calling  code.   By  default
3557       png_error()  and  png_warning() print a message on stderr via fprintf()
3558       unless the library is compiled with PNG_NO_CONSOLE_IO defined  (because
3559       you don't want the messages) or PNG_NO_STDIO defined (because fprintf()
3560       isn't available).  If you wish to change  the  behavior  of  the  error
3561       functions,  you  will need to set up your own message callbacks.  These
3562       functions are normally supplied at the time that the png_struct is cre‐
3563       ated.   It is also possible to redirect errors and warnings to your own
3564       replacement functions after png_create_*_struct() has  been  called  by
3565       calling:
3566
3567           png_set_error_fn(png_structp png_ptr,
3568               png_voidp error_ptr, png_error_ptr error_fn,
3569               png_error_ptr warning_fn);
3570
3571           png_voidp error_ptr = png_get_error_ptr(png_ptr);
3572
3573       If  NULL is supplied for either error_fn or warning_fn, then the libpng
3574       default function will be used, calling fprintf() and/or longjmp() if  a
3575       problem  is  encountered.   The replacement error functions should have
3576       parameters as follows:
3577
3578           void user_error_fn(png_structp png_ptr,
3579               png_const_charp error_msg);
3580           void user_warning_fn(png_structp png_ptr,
3581               png_const_charp warning_msg);
3582
3583       The motivation behind using setjmp() and longjmp() is the C++ throw and
3584       catch  exception  handling methods.  This makes the code much easier to
3585       write, as there is no need to check every return code of every function
3586       call.   However, there are some uncertainties about the status of local
3587       variables after a longjmp, so the user may want  to  be  careful  about
3588       doing  anything after setjmp returns non-zero besides returning itself.
3589       Consult your compiler documentation for more details.  For an  alterna‐
3590       tive  approach,  you  may  wish  to  use  the  "cexcept"  facility (see
3591       http://cexcept.sourceforge.net).
3592
3593
3594   Custom chunks
3595       If you need to read or write custom chunks, you may need to get  deeper
3596       into  the  libpng code.  The library now has mechanisms for storing and
3597       writing chunks of unknown type; you can even declare callbacks for cus‐
3598       tom  chunks.   However, this may not be good enough if the library code
3599       itself needs to know about interactions between your chunk and existing
3600       `intrinsic' chunks.
3601
3602       If you need to write a new intrinsic chunk, first read the PNG specifi‐
3603       cation. Acquire a first level of understanding of how  it  works.   Pay
3604       particular  attention  to  the  sections that describe chunk names, and
3605       look at how other chunks were designed, so you can do things similarly.
3606       Second,  check  out  the sections of libpng that read and write chunks.
3607       Try to find a chunk that is similar to yours and use it as a  template.
3608       More  details can be found in the comments inside the code.  It is best
3609       to handle unknown chunks in a generic method, via  callback  functions,
3610       instead of by modifying libpng functions.
3611
3612       If you wish to write your own transformation for the data, look through
3613       the part of the code that does the transformations, and check out  some
3614       of  the  simpler  ones  to get an idea of how they work.  Try to find a
3615       similar transformation to the one you want to add and copy off  of  it.
3616       More details can be found in the comments inside the code itself.
3617
3618
3619   Configuring for 16 bit platforms
3620       You  will want to look into zconf.h to tell zlib (and thus libpng) that
3621       it cannot allocate more then 64K at a time.  Even if you can, the  mem‐
3622       ory  won't  be accessible.  So limit zlib and libpng to 64K by defining
3623       MAXSEG_64K.
3624
3625
3626   Configuring for DOS
3627       For DOS users who only have access to the lower 640K, you will have  to
3628       limit  zlib's  memory usage via a png_set_compression_mem_level() call.
3629       See zlib.h or zconf.h in the zlib library for more information.
3630
3631
3632   Configuring for Medium Model
3633       Libpng's support for medium model has been tested on most of the  popu‐
3634       lar compilers.  Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
3635       defined, and FAR gets defined to far in pngconf.h, and  you  should  be
3636       all  set.   Everything  in the library (except for zlib's structure) is
3637       expecting far data.  You must use the typedefs with the p or pp on  the
3638       end  for pointers (or at least look at them and be careful).  Make note
3639       that the rows of data are defined as png_bytepp, which is  an  unsigned
3640       char far * far *.
3641
3642
3643   Configuring for gui/windowing platforms:
3644       You will need to write new error and warning functions that use the GUI
3645       interface, as described previously, and set them to be  the  error  and
3646       warning  functions at the time that png_create_*_struct() is called, in
3647       order to have them available during the structure initialization.  They
3648       can  be  changed  later via png_set_error_fn().  On some compilers, you
3649       may also have to change the memory allocators (png_malloc, etc.).
3650
3651
3652   Configuring for compiler xxx:
3653       All includes for libpng are in pngconf.h.  If you need to  add,  change
3654       or  delete  an  include, this is the place to do it.  The includes that
3655       are not needed outside libpng are protected by the PNG_INTERNAL defini‐
3656       tion,  which  is  only defined for those routines inside libpng itself.
3657       The files in libpng proper only  include  png.h,  which  includes  png‐
3658       conf.h.
3659
3660
3661   Configuring zlib:
3662       There  are special functions to configure the compression.  Perhaps the
3663       most useful one changes the compression  level,  which  currently  uses
3664       input compression values in the range 0 - 9.  The library normally uses
3665       the default compression level (Z_DEFAULT_COMPRESSION = 6).  Tests  have
3666       shown  that  for  a large majority of images, compression values in the
3667       range 3-6 compress nearly as well as higher  levels,  and  do  so  much
3668       faster.   For  online  applications it may be desirable to have maximum
3669       speed (Z_BEST_SPEED = 1).  With versions of zlib after v0.99,  you  can
3670       also specify no compression (Z_NO_COMPRESSION = 0), but this would cre‐
3671       ate files larger than just storing the raw bitmap.  You can specify the
3672       compression level by calling:
3673
3674           png_set_compression_level(png_ptr, level);
3675
3676       Another  useful  one is to reduce the memory level used by the library.
3677       The memory level defaults to 8, but it can be lowered if you are  short
3678       on  memory  (running DOS, for example, where you only have 640K).  Note
3679       that the memory level does have an effect on compression;  among  other
3680       things,  lower  levels  will  result in sections of incompressible data
3681       being emitted in smaller stored blocks, with a  correspondingly  larger
3682       relative overhead of up to 15% in the worst case.
3683
3684           png_set_compression_mem_level(png_ptr, level);
3685
3686       The other functions are for configuring zlib.  They are not recommended
3687       for normal use and may result in writing  an  invalid  PNG  file.   See
3688       zlib.h for more information on what these mean.
3689
3690           png_set_compression_strategy(png_ptr,
3691               strategy);
3692           png_set_compression_window_bits(png_ptr,
3693               window_bits);
3694           png_set_compression_method(png_ptr, method);
3695           png_set_compression_buffer_size(png_ptr, size);
3696
3697
3698   Controlling row filtering
3699       If you want to control whether libpng uses filtering or not, which fil‐
3700       ters are used, and how it goes about picking row filters, you can  call
3701       one of these functions.  The selection and configuration of row filters
3702       can have a significant impact on the size  and  encoding  speed  and  a
3703       somewhat lesser impact on the decoding speed of an image.  Filtering is
3704       enabled by default for RGB  and  grayscale  images  (with  and  without
3705       alpha),  but not for paletted images nor for any images with bit depths
3706       less than 8 bits/pixel.
3707
3708       The 'method' parameter sets the main filtering method,  which  is  cur‐
3709       rently  only '0' in the PNG 1.2 specification.  The 'filters' parameter
3710       sets which filter(s), if any, should be used for each scanline.  Possi‐
3711       ble  values are PNG_ALL_FILTERS and PNG_NO_FILTERS to turn filtering on
3712       and off, respectively.
3713
3714       Individual filter types are PNG_FILTER_NONE,  PNG_FILTER_SUB,  PNG_FIL‐
3715       TER_UP,  PNG_FILTER_AVG,  PNG_FILTER_PAETH,  which  can be bitwise ORed
3716       together with '|' to specify one or more filters to use.  These filters
3717       are  described  in more detail in the PNG specification.  If you intend
3718       to change the filter type during the course of writing the  image,  you
3719       should start with flags set for all of the filters you intend to use so
3720       that libpng can initialize its internal  structures  appropriately  for
3721       all  of  the  filter  types.   (Note that this means the first row must
3722       always be adaptively filtered, because libpng currently does not  allo‐
3723       cate  the  filter buffers until png_write_row() is called for the first
3724       time.)
3725
3726           filters = PNG_FILTER_NONE | PNG_FILTER_SUB
3727                     PNG_FILTER_UP | PNG_FILTER_AVG |
3728                     PNG_FILTER_PAETH | PNG_ALL_FILTERS;
3729
3730           png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3731              filters);
3732                     The second parameter can also be
3733                     PNG_INTRAPIXEL_DIFFERENCING if you are
3734                     writing a PNG to be embedded in a MNG
3735                     datastream.  This parameter must be the
3736                     same as the value of filter_method used
3737                     in png_set_IHDR().
3738
3739       It is also possible to influence how  libpng  chooses  from  among  the
3740       available  filters.   This  is  done  in  one  or both of two ways - by
3741       telling it how important it is to keep the same filter  for  successive
3742       rows,  and  by  telling it the relative computational costs of the fil‐
3743       ters.
3744
3745           double weights[3] = {1.5, 1.3, 1.1},
3746              costs[PNG_FILTER_VALUE_LAST] =
3747              {1.0, 1.3, 1.3, 1.5, 1.7};
3748
3749           png_set_filter_heuristics(png_ptr,
3750              PNG_FILTER_HEURISTIC_WEIGHTED, 3,
3751              weights, costs);
3752
3753       The weights are multiplying factors that indicate to  libpng  that  the
3754       row  filter  should  be the same for successive rows unless another row
3755       filter is that many times better than  the  previous  filter.   In  the
3756       above  example,  if the previous 3 filters were SUB, SUB, NONE, the SUB
3757       filter could have a "sum of  absolute  differences"  1.5  x  1.3  times
3758       higher  than  other  filters and still be chosen, while the NONE filter
3759       could have a sum 1.1 times higher than other filters and still be  cho‐
3760       sen.   Unspecified  weights  are  taken  to  be  1.0, and the specified
3761       weights should probably be declining  like  those  above  in  order  to
3762       emphasize recent filters over older filters.
3763
3764       The  filter costs specify for each filter type a relative decoding cost
3765       to be considered when selecting row filters.  This means  that  filters
3766       with  higher costs are less likely to be chosen over filters with lower
3767       costs, unless their "sum of absolute differences" is that much smaller.
3768       The  costs do not necessarily reflect the exact computational speeds of
3769       the various filters, since this would unduly influence the final  image
3770       size.
3771
3772       Note  that  the numbers above were invented purely for this example and
3773       are given only to help explain the function usage.  Little testing  has
3774       been done to find optimum values for either the costs or the weights.
3775
3776
3777   Removing unwanted object code
3778       There  are a bunch of #define's in pngconf.h that control what parts of
3779       libpng are compiled.  All the defines end in _SUPPORTED.   If  you  are
3780       never  going  to use a capability, you can change the #define to #undef
3781       before recompiling libpng and save yourself code and data space, or you
3782       can  turn  off  individual  capabilities  with  defines that begin with
3783       PNG_NO_.
3784
3785       You can also turn all of the transforms and ancillary  chunk  capabili‐
3786       ties  off  en masse with compiler directives that define PNG_NO_READ[or
3787       WRITE]_TRANSFORMS, or PNG_NO_READ[or  WRITE]_ANCILLARY_CHUNKS,  or  all
3788       four, along with directives to turn on any of the capabilities that you
3789       do want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives  disable  the
3790       extra  transformations  but  still  leave  the library fully capable of
3791       reading and writing PNG files with all known public chunks. Use of  the
3792       PNG_NO_READ[or  WRITE]_ANCILLARY_CHUNKS  directive  produces  a library
3793       that is incapable of reading or writing ancillary chunks.  If  you  are
3794       not  using  the  progressive  reading capability, you can turn that off
3795       with PNG_NO_PROGRESSIVE_READ (don't confuse this with  the  INTERLACING
3796       capability, which you'll still have).
3797
3798       All the reading and writing specific code are in separate files, so the
3799       linker should only grab the files it needs.  However, if  you  want  to
3800       make  sure, or if you are building a stand alone library, all the read‐
3801       ing files start with pngr and all the writing files  start  with  pngw.
3802       The  files  that don't match either (like png.c, pngtrans.c, etc.)  are
3803       used for both reading and writing, and always need to be included.  The
3804       progressive reader is in pngpread.c
3805
3806       If you are creating or distributing a dynamically linked library (a .so
3807       or DLL file), you should  not  remove  or  disable  any  parts  of  the
3808       library, as this will cause applications linked with different versions
3809       of the library to fail if they call functions  not  available  in  your
3810       library.   The  size  of  the  library  itself  should not be an issue,
3811       because only those sections that are actually used will be loaded  into
3812       memory.
3813
3814
3815   Requesting debug printout
3816       The  macro definition PNG_DEBUG can be used to request debugging print‐
3817       out.  Set it to an integer value in the range 0 to 3.   Higher  numbers
3818       result in increasing amounts of debugging information.  The information
3819       is printed to the "stderr" file, unless another file name is  specified
3820       in the PNG_DEBUG_FILE macro definition.
3821
3822       When PNG_DEBUG > 0, the following functions (macros) become available:
3823
3824          png_debug(level, message)
3825          png_debug1(level, message, p1)
3826          png_debug2(level, message, p1, p2)
3827
3828       in  which  "level"  is compared to PNG_DEBUG to decide whether to print
3829       the message, "message" is the formatted string to be  printed,  and  p1
3830       and  p2  are parameters that are to be embedded in the string according
3831       to printf-style formatting directives.  For example,
3832
3833          png_debug1(2, "foo=%d0, foo);
3834
3835       is expanded to
3836
3837          if(PNG_DEBUG > 2)
3838            fprintf(PNG_DEBUG_FILE, "foo=%d0, foo);
3839
3840       When PNG_DEBUG is defined but is zero, the macros aren't  defined,  but
3841       you can still use PNG_DEBUG to control your own debugging:
3842
3843          #ifdef PNG_DEBUG
3844              fprintf(stderr, ...
3845          #endif
3846
3847       When  PNG_DEBUG  = 1, the macros are defined, but only png_debug state‐
3848       ments having level = 0 will be printed.  There aren't any  such  state‐
3849       ments  in  this  version of libpng, but if you insert some they will be
3850       printed.
3851
3852

VI. MNG support

3854       The  MNG  specification  (available  at  http://www.libpng.org/pub/mng)
3855       allows  certain  extensions  to PNG for PNG images that are embedded in
3856       MNG datastreams.  Libpng can support  some  of  these  extensions.   To
3857       enable them, use the png_permit_mng_features() function:
3858
3859          feature_set = png_permit_mng_features(png_ptr, mask)
3860          mask is a png_uint_32 containing the bitwise OR of the
3861               features you want to enable.  These include
3862               PNG_FLAG_MNG_EMPTY_PLTE
3863               PNG_FLAG_MNG_FILTER_64
3864               PNG_ALL_MNG_FEATURES
3865          feature_set is a png_uint_32 that is the bitwise AND of
3866             your mask with the set of MNG features that is
3867             supported by the version of libpng that you are using.
3868
3869       It  is  an  error to use this function when reading or writing a stand‐
3870       alone PNG file with the PNG 8-byte signature.  The PNG datastream  must
3871       be  wrapped  in  a  MNG datastream.  As a minimum, it must have the MNG
3872       8-byte signature and the MHDR and MEND chunks.  Libpng does not provide
3873       support  for  these or any other MNG chunks; your application must pro‐
3874       vide its own support for them.  You may wish to consider  using  libmng
3875       (available at http://www.libmng.com) instead.
3876
3877

VII. Changes to Libpng from version 0.88

3879       It should be noted that versions of libpng later than 0.96 are not dis‐
3880       tributed by the original libpng author, Guy Schalnat,  nor  by  Andreas
3881       Dilger,  who had taken over from Guy during 1996 and 1997, and distrib‐
3882       uted versions 0.89 through 0.96, but rather by another  member  of  the
3883       original  PNG  Group, Glenn Randers-Pehrson.  Guy and Andreas are still
3884       alive and well, but they have moved on to other things.
3885
3886       The   old   libpng   functions    png_read_init(),    png_write_init(),
3887       png_info_init(),  png_read_destroy(), and png_write_destroy() have been
3888       moved to PNG_INTERNAL in version 0.95 to discourage their  use.   These
3889       functions will be removed from libpng version 2.0.0.
3890
3891       The preferred method of creating and initializing the libpng structures
3892       is via  the  png_create_read_struct(),  png_create_write_struct(),  and
3893       png_create_info_struct()  because  they  isolate the size of the struc‐
3894       tures from the application, allow  version  error  checking,  and  also
3895       allow  the use of custom error handling routines during the initializa‐
3896       tion, which the old functions do not.  The functions png_read_destroy()
3897       and  png_write_destroy()  do  not  actually free the memory that libpng
3898       allocated for these structs, but just reset  the  data  structures,  so
3899       they   can   be   used   instead   of   png_destroy_read_struct()   and
3900       png_destroy_write_struct() if you feel there is too much  system  over‐
3901       head allocating and freeing the png_struct for each image read.
3902
3903       Setting   the   error   callbacks   via   png_set_message_fn()   before
3904       png_read_init() as was suggested in libpng-0.88 is no longer  supported
3905       because this caused applications that do not use custom error functions
3906       to fail if the png_ptr was not initialized to zero.  It is still possi‐
3907       ble to set the error callbacks AFTER png_read_init(), or to change them
3908       with png_set_error_fn(), which is essentially the  same  function,  but
3909       with  a new name to force compilation errors with applications that try
3910       to use the old method.
3911
3912       Starting with version 1.0.7, you can find  out  which  version  of  the
3913       library you are using at run-time:
3914
3915          png_uint_32 libpng_vn = png_access_version_number();
3916
3917       The  number libpng_vn is constructed from the major version, minor ver‐
3918       sion with leading zero, and release number with  leading  zero,  (e.g.,
3919       libpng_vn for version 1.0.7 is 10007).
3920
3921       You  can also check which version of png.h you used when compiling your
3922       application:
3923
3924          png_uint_32 application_vn = PNG_LIBPNG_VER;
3925
3926

VIII. Changes to Libpng from version 1.0.x to 1.2.x

3928       Support for user memory management was enabled by default.   To  accom‐
3929       plish   this,   the   functions   png_create_read_struct_2(),  png_cre‐
3930       ate_write_struct_2(),  png_set_mem_fn(),  png_get_mem_ptr(),   png_mal‐
3931       loc_default(), and png_free_default() were added.
3932
3933       Support  for  the  iTXt chunk has been enabled by default as of version
3934       1.2.41.
3935
3936       Support for certain MNG features was enabled.
3937
3938       Support for numbered error messages was added.  However, we  never  got
3939       around   to  actually  numbering  the  error  messages.   The  function
3940       png_set_strip_error_numbers() was added (Note: the prototype  for  this
3941       function  was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
3942       builds of libpng-1.2.15.  It was restored in libpng-1.2.36).
3943
3944       The png_malloc_warn() function was added at libpng-1.2.3.  This  issues
3945       a  png_warning  and  returns  NULL instead of aborting when it fails to
3946       acquire the requested memory allocation.
3947
3948       Support for setting user limits on image width and height  was  enabled
3949       by       default.        The      functions      png_set_user_limits(),
3950       png_get_user_width_max(), and png_get_user_height_max() were  added  at
3951       libpng-1.2.6.
3952
3953       The png_set_add_alpha() function was added at libpng-1.2.7.
3954
3955       The    function    png_set_expand_gray_1_2_4_to_8()    was   added   at
3956       libpng-1.2.9.  Unlike png_set_gray_1_2_4_to_8(), the new function  does
3957       not expand the tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() func‐
3958       tion is deprecated.
3959
3960       A number of macro definitions in support of runtime selection of assem‐
3961       bler  code  features  (especially Intel MMX code support) were added at
3962       libpng-1.2.0:
3963
3964           PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
3965           PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
3966           PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
3967           PNG_ASM_FLAG_MMX_READ_INTERLACE
3968           PNG_ASM_FLAG_MMX_READ_FILTER_SUB
3969           PNG_ASM_FLAG_MMX_READ_FILTER_UP
3970           PNG_ASM_FLAG_MMX_READ_FILTER_AVG
3971           PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
3972           PNG_ASM_FLAGS_INITIALIZED
3973           PNG_MMX_READ_FLAGS
3974           PNG_MMX_FLAGS
3975           PNG_MMX_WRITE_FLAGS
3976           PNG_MMX_FLAGS
3977
3978       We added the following functions in support  of  runtime  selection  of
3979       assembler code features:
3980
3981           png_get_mmx_flagmask()
3982           png_set_mmx_thresholds()
3983           png_get_asm_flags()
3984           png_get_mmx_bitdepth_threshold()
3985           png_get_mmx_rowbytes_threshold()
3986           png_set_asm_flags()
3987
3988       We  replaced all of these functions with simple stubs in libpng-1.2.20,
3989       when the Intel assembler code was removed due to a licensing issue.
3990
3991       These macros are deprecated:
3992
3993           PNG_READ_TRANSFORMS_NOT_SUPPORTED
3994           PNG_PROGRESSIVE_READ_NOT_SUPPORTED
3995           PNG_NO_SEQUENTIAL_READ_SUPPORTED
3996           PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
3997           PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
3998           PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
3999
4000       They have been replaced, respectively, by:
4001
4002           PNG_NO_READ_TRANSFORMS
4003           PNG_NO_PROGRESSIVE_READ
4004           PNG_NO_SEQUENTIAL_READ
4005           PNG_NO_WRITE_TRANSFORMS
4006           PNG_NO_READ_ANCILLARY_CHUNKS
4007           PNG_NO_WRITE_ANCILLARY_CHUNKS
4008
4009       PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been deprecated
4010       since libpng-1.0.16 and libpng-1.2.6.
4011
4012       The function
4013           png_check_sig(sig, num) was replaced with
4014           !png_sig_cmp(sig, 0, num) It has been deprecated since libpng-0.90.
4015
4016       The function
4017           png_set_gray_1_2_4_to_8()  which  also  expands  tRNS  to alpha was
4018       replaced with
4019           png_set_expand_gray_1_2_4_to_8() which does not. It has been depre‐
4020       cated since libpng-1.0.18 and 1.2.9.
4021
4022

IX. (Omitted)

X. Detecting libpng

4025       The  png_get_io_ptr()  function has been present since libpng-0.88, has
4026       never changed, and is unaffected by conditional compilation macros.  It
4027       is the best choice for use in configure scripts for detecting the pres‐
4028       ence of any libpng version since 0.88.  In an  autoconf  "configure.in"
4029       you could use
4030
4031           AC_CHECK_LIB(png, png_get_io_ptr, ...
4032
4033

XI. Source code repository

4035       Since  about February 2009, version 1.2.34, libpng has been under "git"
4036       source  control.   The  git  repository  was  built  from  old  libpng-
4037       x.y.z.tar.gz  files going back to version 0.70.  You can access the git
4038       repository (read only) at
4039
4040           git://libpng.git.sourceforge.net/gitroot/libpng
4041
4042       or you can browse it via "gitweb" at
4043
4044           http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
4045
4046       Patches can be sent to glennrp at users.sourceforge.net or to  png-mng-
4047       implement at lists.sourceforge.net or you can upload them to the libpng
4048       bug tracker at
4049
4050           http://libpng.sourceforge.net
4051
4052

XII. Coding style

4054       Our coding style is similar to the "Allman" style, with curly braces on
4055       separate lines:
4056
4057           if (condition)
4058           {
4059              action;
4060           }
4061
4062           else if (another condition)
4063           {
4064              another action;
4065           }
4066
4067       The braces can be omitted from simple one-line actions:
4068
4069           if (condition)
4070              return (0);
4071
4072       We  use  3-space indentation, except for continued statements which are
4073       usually indented the same as the first line of the statement plus  four
4074       more spaces.
4075
4076       For  macro  definitions  we use 2-space indentation, always leaving the
4077       "#" in the first column.
4078
4079           #ifndef PNG_NO_FEATURE
4080           #  ifndef PNG_FEATURE_SUPPORTED
4081           #    define PNG_FEATURE_SUPPORTED
4082           #  endif
4083           #endif
4084
4085       Comments appear with the leading "/*" at the same  indentation  as  the
4086       statement that follows the comment:
4087
4088           /* Single-line comment */
4089           statement;
4090
4091           /* Multiple-line
4092            * comment
4093            */
4094           statement;
4095
4096       Very  short comments can be placed at the end of the statement to which
4097       they pertain:
4098
4099           statement;    /* comment */
4100
4101       We don't use C++ style ("//") comments. We have, however, used them  in
4102       the past in some now-abandoned MMX assembler code.
4103
4104       Functions  and  their curly braces are not indented, and exported func‐
4105       tions are marked with PNGAPI:
4106
4107        /* This is a public function that is visible to
4108         * application programers. It does thus-and-so.
4109         */
4110        void PNGAPI
4111        png_exported_function(png_ptr, png_info, foo)
4112        {
4113           body;
4114        }
4115
4116       The prototypes for all exported functions appear in  png.h,  above  the
4117       comment that says
4118
4119           /* Maintainer: Put new public prototypes here ... */
4120
4121       We mark all non-exported functions with "/* PRIVATE */"":
4122
4123        void /* PRIVATE */
4124        png_non_exported_function(png_ptr, png_info, foo)
4125        {
4126           body;
4127        }
4128
4129       The prototypes for non-exported functions (except for those in pngtest)
4130       appear in the PNG_INTERNAL section of png.h above the comment that says
4131
4132         /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
4133
4134       The names of all exported functions and variables begin  with   "png_",
4135       and all publicly visible C preprocessor macros begin with "PNG_".
4136
4137       We put a space after each comma and after each semicolon in "for" stat‐
4138       ments, and we put spaces before and after each C  binary  operator  and
4139       after  "for"  or  "while".  We don't put a space between a typecast and
4140       the expression being cast, nor do we put one between  a  function  name
4141       and the left parenthesis that follows it:
4142
4143           for (i = 2; i > 0; --i)
4144              y[i] = a(x) + (int)b;
4145
4146       We  prefer  #ifdef  and #ifndef to #if defined() and if !defined() when
4147       there is only one macro being tested.
4148
4149       We do not use the TAB character for indentation in the C sources.
4150
4151       Lines do not exceed 80 characters.
4152
4153       Other rules can be inferred by inspecting the libpng source.
4154
4155

XIII. Y2K Compliance in libpng

4157       July 9, 2011
4158
4159       Since the PNG Development group is an ad-hoc body,  we  can't  make  an
4160       official declaration.
4161
4162       This  is  your  unofficial  assurance that libpng from version 0.71 and
4163       upward through 1.2.46 are Y2K compliant.  It is my belief that  earlier
4164       versions were also Y2K compliant.
4165
4166       Libpng  only  has  three year fields.  One is a 2-byte unsigned integer
4167       that will hold years up to 65535.  The other two hold the date in  text
4168       format, and will hold years up to 9999.
4169
4170       The integer is
4171           "png_uint_16 year" in png_time_struct.
4172
4173       The strings are
4174           "png_charp time_buffer" in png_struct and
4175           "near_time_buffer", which is a local character string in png.c.
4176
4177       There are seven time-related functions:
4178
4179           png_convert_to_rfc_1123() in png.c
4180             (formerly png_convert_to_rfc_1152() in error)
4181           png_convert_from_struct_tm() in pngwrite.c, called
4182             in pngwrite.c
4183           png_convert_from_time_t() in pngwrite.c
4184           png_get_tIME() in pngget.c
4185           png_handle_tIME() in pngrutil.c, called in pngread.c
4186           png_set_tIME() in pngset.c
4187           png_write_tIME() in pngwutil.c, called in pngwrite.c
4188
4189       All appear to handle dates properly in a Y2K environment.  The png_con‐
4190       vert_from_time_t() function calls gmtime() to convert from system clock
4191       time,  which  returns  (year  - 1900), which we properly convert to the
4192       full 4-digit year.  There is  a  possibility  that  applications  using
4193       libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
4194       function, or that they are incorrectly  passing  only  a  2-digit  year
4195       instead  of  "year  - 1900" into the png_convert_from_struct_tm() func‐
4196       tion, but this is not under our control.  The libpng documentation  has
4197       always  stated that it works with 4-digit years, and the APIs have been
4198       documented as such.
4199
4200       The tIME chunk itself is also Y2K compliant.  It uses a 2-byte unsigned
4201       integer to hold the year, and can hold years as large as 65535.
4202
4203       zlib, upon which libpng depends, is also Y2K compliant.  It contains no
4204       date-related code.
4205
4206
4207          Glenn Randers-Pehrson
4208          libpng maintainer
4209          PNG Development Group
4210
4211

NOTE

4213       Note about libpng version numbers:
4214
4215       Due to various miscommunications, unforeseen code incompatibilities and
4216       occasional  factors  outside the authors' control, version numbering on
4217       the library has not always been consistent  and  straightforward.   The
4218       following  table  summarizes matters since version 0.89c, which was the
4219       first widely used release:
4220
4221        source             png.h  png.h  shared-lib
4222        version            string   int  version
4223        -------            ------  ----- ----------
4224        0.89c ("beta 3")  0.89       89  1.0.89
4225        0.90  ("beta 4")  0.90       90  0.90
4226        0.95  ("beta 5")  0.95       95  0.95
4227        0.96  ("beta 6")  0.96       96  0.96
4228        0.97b ("beta 7")  1.00.97    97  1.0.1
4229        0.97c             0.97       97  2.0.97
4230        0.98              0.98       98  2.0.98
4231        0.99              0.99       98  2.0.99
4232        0.99a-m           0.99       99  2.0.99
4233        1.00              1.00      100  2.1.0
4234        1.0.0             1.0.0     100  2.1.0
4235        1.0.0   (from here on, the  100  2.1.0
4236        1.0.1    png.h string is  10001  2.1.0
4237        1.0.1a-e identical to the 10002  from here on, the
4238        1.0.2    source version)  10002  shared library is 2.V
4239        1.0.2a-b                  10003  where V is the source
4240        1.0.1                     10001  code version except as
4241        1.0.1a-e                  10002  2.1.0.1a-e   noted.
4242        1.0.2                     10002  2.1.0.2
4243        1.0.2a-b                  10003  2.1.0.2a-b
4244        1.0.3                     10003  2.1.0.3
4245        1.0.3a-d                  10004  2.1.0.3a-d
4246        1.0.4                     10004  2.1.0.4
4247        1.0.4a-f                  10005  2.1.0.4a-f
4248        1.0.5 (+ 2 patches)       10005  2.1.0.5
4249        1.0.5a-d                  10006  2.1.0.5a-d
4250        1.0.5e-r                  10100  2.1.0.5e-r
4251        1.0.5s-v                  10006  2.1.0.5s-v
4252        1.0.6 (+ 3 patches)       10006  2.1.0.6
4253        1.0.6d-g                  10007  2.1.0.6d-g
4254        1.0.6h                    10007  10.6h
4255        1.0.6i                    10007  10.6i
4256        1.0.6j                    10007  2.1.0.6j
4257        1.0.7beta11-14    DLLNUM  10007  2.1.0.7beta11-14
4258        1.0.7beta15-18       1    10007  2.1.0.7beta15-18
4259        1.0.7rc1-2           1    10007  2.1.0.7rc1-2
4260        1.0.7                1    10007  2.1.0.7
4261        1.0.8beta1-4         1    10008  2.1.0.8beta1-4
4262        1.0.8rc1             1    10008  2.1.0.8rc1
4263        1.0.8                1    10008  2.1.0.8
4264        1.0.9beta1-6         1    10009  2.1.0.9beta1-6
4265        1.0.9rc1             1    10009  2.1.0.9rc1
4266        1.0.9beta7-10        1    10009  2.1.0.9beta7-10
4267        1.0.9rc2             1    10009  2.1.0.9rc2
4268        1.0.9                1    10009  2.1.0.9
4269        1.0.10beta1          1    10010  2.1.0.10beta1
4270        1.0.10rc1            1    10010  2.1.0.10rc1
4271        1.0.10               1    10010  2.1.0.10
4272        1.0.11beta1-3        1    10011  2.1.0.11beta1-3
4273        1.0.11rc1            1    10011  2.1.0.11rc1
4274        1.0.11               1    10011  2.1.0.11
4275        1.0.12beta1-2        2    10012  2.1.0.12beta1-2
4276        1.0.12rc1            2    10012  2.1.0.12rc1
4277        1.0.12               2    10012  2.1.0.12
4278        1.1.0a-f             -    10100  2.1.1.0a-f abandoned
4279        1.2.0beta1-2         2    10200  2.1.2.0beta1-2
4280        1.2.0beta3-5         3    10200  3.1.2.0beta3-5
4281        1.2.0rc1             3    10200  3.1.2.0rc1
4282        1.2.0                3    10200  3.1.2.0
4283        1.2.1beta-4          3    10201  3.1.2.1beta1-4
4284        1.2.1rc1-2           3    10201  3.1.2.1rc1-2
4285        1.2.1                3    10201  3.1.2.1
4286        1.2.2beta1-6        12    10202  12.so.0.1.2.2beta1-6
4287        1.0.13beta1         10    10013  10.so.0.1.0.13beta1
4288        1.0.13rc1           10    10013  10.so.0.1.0.13rc1
4289        1.2.2rc1            12    10202  12.so.0.1.2.2rc1
4290        1.0.13              10    10013  10.so.0.1.0.13
4291        1.2.2               12    10202  12.so.0.1.2.2
4292        1.2.3rc1-6          12    10203  12.so.0.1.2.3rc1-6
4293        1.2.3               12    10203  12.so.0.1.2.3
4294        1.2.4beta1-3        13    10204  12.so.0.1.2.4beta1-3
4295        1.2.4rc1            13    10204  12.so.0.1.2.4rc1
4296        1.0.14              10    10014  10.so.0.1.0.14
4297        1.2.4               13    10204  12.so.0.1.2.4
4298        1.2.5beta1-2        13    10205  12.so.0.1.2.5beta1-2
4299        1.0.15rc1           10    10015  10.so.0.1.0.15rc1
4300        1.0.15              10    10015  10.so.0.1.0.15
4301        1.2.5               13    10205  12.so.0.1.2.5
4302        1.2.6beta1-4        13    10206  12.so.0.1.2.6beta1-4
4303        1.2.6rc1-5          13    10206  12.so.0.1.2.6rc1-5
4304        1.0.16              10    10016  10.so.0.1.0.16
4305        1.2.6               13    10206  12.so.0.1.2.6
4306        1.2.7beta1-2        13    10207  12.so.0.1.2.7beta1-2
4307        1.0.17rc1           10    10017  10.so.0.1.0.17rc1
4308        1.2.7rc1            13    10207  12.so.0.1.2.7rc1
4309        1.0.17              10    10017  10.so.0.1.0.17
4310        1.2.7               13    10207  12.so.0.1.2.7
4311        1.2.8beta1-5        13    10208  12.so.0.1.2.8beta1-5
4312        1.0.18rc1-5         10    10018  10.so.0.1.0.18rc1-5
4313        1.2.8rc1-5          13    10208  12.so.0.1.2.8rc1-5
4314        1.0.18              10    10018  10.so.0.1.0.18
4315        1.2.8               13    10208  12.so.0.1.2.8
4316        1.2.9beta1-3        13    10209  12.so.0.1.2.9beta1-3
4317        1.2.9beta4-11       13    10209  12.so.0.9[.0]
4318        1.2.9rc1            13    10209  12.so.0.9[.0]
4319        1.2.9               13    10209  12.so.0.9[.0]
4320        1.2.10beta1-8       13    10210  12.so.0.10[.0]
4321        1.2.10rc1-3         13    10210  12.so.0.10[.0]
4322        1.2.10              13    10210  12.so.0.10[.0]
4323        1.2.11beta1-4       13    10211  12.so.0.11[.0]
4324        1.0.19rc1-5         10    10019  10.so.0.19[.0]
4325        1.2.11rc1-5         13    10211  12.so.0.11[.0]
4326        1.0.19              10    10019  10.so.0.19[.0]
4327        1.2.11              13    10211  12.so.0.11[.0]
4328        1.0.20              10    10020  10.so.0.20[.0]
4329        1.2.12              13    10212  12.so.0.12[.0]
4330        1.2.13beta1         13    10213  12.so.0.13[.0]
4331        1.0.21              10    10021  10.so.0.21[.0]
4332        1.2.13              13    10213  12.so.0.13[.0]
4333        1.2.14beta1-2       13    10214  12.so.0.14[.0]
4334        1.0.22rc1           10    10022  10.so.0.22[.0]
4335        1.2.14rc1           13    10214  12.so.0.14[.0]
4336        1.2.15beta1-6       13    10215  12.so.0.15[.0]
4337        1.0.23rc1-5         10    10023  10.so.0.23[.0]
4338        1.2.15rc1-5         13    10215  12.so.0.15[.0]
4339        1.0.23              10    10023  10.so.0.23[.0]
4340        1.2.15              13    10215  12.so.0.15[.0]
4341        1.2.16beta1-2       13    10216  12.so.0.16[.0]
4342        1.2.16rc1           13    10216  12.so.0.16[.0]
4343        1.0.24              10    10024  10.so.0.24[.0]
4344        1.2.16              13    10216  12.so.0.16[.0]
4345        1.2.17beta1-2       13    10217  12.so.0.17[.0]
4346        1.0.25rc1           10    10025  10.so.0.25[.0]
4347        1.2.17rc1-3         13    10217  12.so.0.17[.0]
4348        1.0.25              10    10025  10.so.0.25[.0]
4349        1.2.17              13    10217  12.so.0.17[.0]
4350        1.0.26              10    10026  10.so.0.26[.0]
4351        1.2.18              13    10218  12.so.0.18[.0]
4352        1.2.19beta1-31      13    10219  12.so.0.19[.0]
4353        1.0.27rc1-6         10    10027  10.so.0.27[.0]
4354        1.2.19rc1-6         13    10219  12.so.0.19[.0]
4355        1.0.27              10    10027  10.so.0.27[.0]
4356        1.2.19              13    10219  12.so.0.19[.0]
4357        1.2.20beta01-04     13    10220  12.so.0.20[.0]
4358        1.0.28rc1-6         10    10028  10.so.0.28[.0]
4359        1.2.20rc1-6         13    10220  12.so.0.20[.0]
4360        1.0.28              10    10028  10.so.0.28[.0]
4361        1.2.20              13    10220  12.so.0.20[.0]
4362        1.2.21beta1-2       13    10221  12.so.0.21[.0]
4363        1.2.21rc1-3         13    10221  12.so.0.21[.0]
4364        1.0.29              10    10029  10.so.0.29[.0]
4365        1.2.21              13    10221  12.so.0.21[.0]
4366        1.2.22beta1-4       13    10222  12.so.0.22[.0]
4367        1.0.30rc1           13    10030  10.so.0.30[.0]
4368        1.2.22rc1           13    10222  12.so.0.22[.0]
4369        1.0.30              10    10030  10.so.0.30[.0]
4370        1.2.22              13    10222  12.so.0.22[.0]
4371        1.2.23beta01-05     13    10223  12.so.0.23[.0]
4372        1.2.23rc01          13    10223  12.so.0.23[.0]
4373        1.2.23              13    10223  12.so.0.23[.0]
4374        1.2.24beta01-02     13    10224  12.so.0.24[.0]
4375        1.2.24rc01          13    10224  12.so.0.24[.0]
4376        1.2.24              13    10224  12.so.0.24[.0]
4377        1.2.25beta01-06     13    10225  12.so.0.25[.0]
4378        1.2.25rc01-02       13    10225  12.so.0.25[.0]
4379        1.0.31              10    10031  10.so.0.31[.0]
4380        1.2.25              13    10225  12.so.0.25[.0]
4381        1.2.26beta01-06     13    10226  12.so.0.26[.0]
4382        1.2.26rc01          13    10226  12.so.0.26[.0]
4383        1.2.26              13    10226  12.so.0.26[.0]
4384        1.0.32              10    10032  10.so.0.32[.0]
4385        1.2.27beta01-06     13    10227  12.so.0.27[.0]
4386        1.2.27rc01          13    10227  12.so.0.27[.0]
4387        1.0.33              10    10033  10.so.0.33[.0]
4388        1.2.27              13    10227  12.so.0.27[.0]
4389        1.0.34              10    10034  10.so.0.34[.0]
4390        1.2.28              13    10228  12.so.0.28[.0]
4391        1.2.29beta01-03     13    10229  12.so.0.29[.0]
4392        1.2.29rc01          13    10229  12.so.0.29[.0]
4393        1.0.35              10    10035  10.so.0.35[.0]
4394        1.2.29              13    10229  12.so.0.29[.0]
4395        1.0.37              10    10037  10.so.0.37[.0]
4396        1.2.30beta01-04     13    10230  12.so.0.30[.0]
4397        1.0.38rc01-08       10    10038  10.so.0.38[.0]
4398        1.2.30rc01-08       13    10230  12.so.0.30[.0]
4399        1.0.38              10    10038  10.so.0.38[.0]
4400        1.2.30              13    10230  12.so.0.30[.0]
4401        1.0.39rc01-03       10    10039  10.so.0.39[.0]
4402        1.2.31rc01-03       13    10231  12.so.0.31[.0]
4403        1.0.39              10    10039  10.so.0.39[.0]
4404        1.2.31              13    10231  12.so.0.31[.0]
4405        1.2.32beta01-02     13    10232  12.so.0.32[.0]
4406        1.0.40rc01          10    10040  10.so.0.40[.0]
4407        1.2.32rc01          13    10232  12.so.0.32[.0]
4408        1.0.40              10    10040  10.so.0.40[.0]
4409        1.2.32              13    10232  12.so.0.32[.0]
4410        1.2.33beta01-02     13    10233  12.so.0.33[.0]
4411        1.2.33rc01-02       13    10233  12.so.0.33[.0]
4412        1.0.41rc01          10    10041  10.so.0.41[.0]
4413        1.2.33              13    10233  12.so.0.33[.0]
4414        1.0.41              10    10041  10.so.0.41[.0]
4415        1.2.34beta01-07     13    10234  12.so.0.34[.0]
4416        1.0.42rc01          10    10042  10.so.0.42[.0]
4417        1.2.34rc01          13    10234  12.so.0.34[.0]
4418        1.0.42              10    10042  10.so.0.42[.0]
4419        1.2.34              13    10234  12.so.0.34[.0]
4420        1.2.35beta01-03     13    10235  12.so.0.35[.0]
4421        1.0.43rc01-02       10    10043  10.so.0.43[.0]
4422        1.2.35rc01-02       13    10235  12.so.0.35[.0]
4423        1.0.43              10    10043  10.so.0.43[.0]
4424        1.2.35              13    10235  12.so.0.35[.0]
4425        1.2.36beta01-05     13    10236  12.so.0.36[.0]
4426        1.2.36rc01          13    10236  12.so.0.36[.0]
4427        1.0.44              10    10044  10.so.0.44[.0]
4428        1.2.36              13    10236  12.so.0.36[.0]
4429        1.2.37beta01-03     13    10237  12.so.0.37[.0]
4430        1.2.37rc01          13    10237  12.so.0.37[.0]
4431        1.2.37              13    10237  12.so.0.37[.0]
4432        1.0.45              10    10045  12.so.0.45[.0]
4433        1.0.46              10    10046  10.so.0.46[.0]
4434        1.2.38beta01        13    10238  12.so.0.38[.0]
4435        1.2.38rc01-03       13    10238  12.so.0.38[.0]
4436        1.0.47              10    10047  10.so.0.47[.0]
4437        1.2.38              13    10238  12.so.0.38[.0]
4438        1.2.39beta01-05     13    10239  12.so.0.39[.0]
4439        1.2.39rc01          13    10239  12.so.0.39[.0]
4440        1.0.48              10    10048  10.so.0.48[.0]
4441        1.2.39              13    10239  12.so.0.39[.0]
4442        1.2.40beta01        13    10240  12.so.0.40[.0]
4443        1.2.40rc01          13    10240  12.so.0.40[.0]
4444        1.0.49              10    10049  10.so.0.49[.0]
4445        1.2.40              13    10240  12.so.0.40[.0]
4446        1.0.50              10    10050  10.so.0.50[.0]
4447        1.2.41beta01-18     13    10241  12.so.0.41[.0]
4448        1.0.51rc01          10    10051  10.so.0.51[.0]
4449        1.2.41rc01-03       13    10241  12.so.0.41[.0]
4450        1.0.51              10    10051  10.so.0.51[.0]
4451        1.2.41              13    10241  12.so.0.41[.0]
4452        1.2.42beta01-02     13    10242  12.so.0.42[.0]
4453        1.2.42rc01-05       13    10242  12.so.0.42[.0]
4454        1.0.52              10    10052  10.so.0.52[.0]
4455        1.2.42              13    10242  12.so.0.42[.0]
4456        1.2.43beta01-05     13    10243  12.so.0.43[.0]
4457        1.0.53rc01-02       10    10053  10.so.0.53[.0]
4458        1.2.43rc01-02       13    10243  12.so.0.43[.0]
4459        1.0.53              10    10053  10.so.0.53[.0]
4460        1.2.43              13    10243  12.so.0.43[.0]
4461        1.2.44beta01-03     13    10244  12.so.0.44[.0]
4462        1.2.44rc01-03       13    10244  12.so.0.44[.0]
4463        1.2.44              13    10244  12.so.0.44[.0]
4464        1.2.45beta01-03     13    10245  12.so.0.45[.0]
4465        1.0.55rc01          10    10055  10.so.0.55[.0]
4466        1.2.45rc01          13    10245  12.so.0.45[.0]
4467        1.0.55              10    10055  10.so.0.55[.0]
4468        1.2.45              13    10245  12.so.0.45[.0]
4469        1.2.46rc01-02       13    10246  12.so.0.46[.0]
4470        1.0.56              10    10056  10.so.0.56[.0]
4471        1.2.46              13    10246  12.so.0.46[.0]
4472
4473       Henceforth the source version will match the shared-library  minor  and
4474       patch numbers; the shared-library major version number will be used for
4475       changes  in  backward  compatibility,   as   it   is   intended.    The
4476       PNG_PNGLIB_VER  macro, which is not used within libpng but is available
4477       for applications, is an unsigned integer of the form xyyzz  correspond‐
4478       ing  to the source version x.y.z (leading zeros in y and z).  Beta ver‐
4479       sions were given the previous public  release  number  plus  a  letter,
4480       until  version 1.0.6j; from then on they were given the upcoming public
4481       release number plus "betaNN" or "rcN".
4482
4483

SEE ALSO

4485       libpngpf(3), png(5)
4486
4487       libpng:
4488
4489              http://libpng.sourceforge.net  (follow  the   [DOWNLOAD]   link)
4490              http://www.libpng.org/pub/png
4491
4492
4493       zlib:
4494
4495              (generally) at the same location as libpng or at
4496              ftp://ftp.info-zip.org/pub/infozip/zlib
4497
4498
4499       PNGspecification:RFC2083
4500
4501              (generally) at the same location as libpng or at
4502              ftp://ftp.rfc-editor.org:/in-notes/rfc2083.txt
4503              or (as a W3C Recommendation) at
4504              http://www.w3.org/TR/REC-png.html
4505
4506
4507       In the case of any inconsistency between the PNG specification and this
4508       library, the specification takes precedence.
4509
4510

AUTHORS

4512       This man page: Glenn Randers-Pehrson <glennrp at users.sourceforge.net>
4513
4514       The contributing authors would like to thank all those who helped  with
4515       testing,  bug  fixes,  and  patience.  This wouldn't have been possible
4516       without all of you.
4517
4518       Thanks to Frank J. T. Wojcik for helping with the documentation.
4519
4520       Libpng version 1.2.46 - July 9, 2011: Initially created in 1995 by  Guy
4521       Eric  Schalnat,  then  of Group 42, Inc.  Currently maintained by Glenn
4522       Randers-Pehrson (glennrp at users.sourceforge.net).
4523
4524       Supported by the PNG development group
4525       png-mng-implement at lists.sf.net (subscription  required;  visit  png-
4526       mng-implement  at  lists.sourceforge.net  (subscription required; visit
4527       https://lists.sourceforge.net/lists/listinfo/png-mng-implement to  sub‐
4528       scribe).
4529
4530
4532       (This  copy of the libpng notices is provided for your convenience.  In
4533       case of any discrepancy between this copy and the notices in  the  file
4534       png.h  that  is  included  in the libpng distribution, the latter shall
4535       prevail.)
4536
4537       If you modify libpng you may insert additional notices immediately fol‐
4538       lowing this sentence.
4539
4540       This code is released under the libpng license.
4541
4542       libpng  versions  1.2.6, August 15, 2004, through 1.2.46, July 9, 2011,
4543       are Copyright (c) 2004,2006-2008 Glenn Randers-Pehrson,  and  are  dis‐
4544       tributed  according  to the same disclaimer and license as libpng-1.2.5
4545       with the following individual added to the list of Contributing Authors
4546
4547          Cosmin Truta
4548
4549       libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October  3,  2002,
4550       are  Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are distributed
4551       according to the same disclaimer and license as libpng-1.0.6  with  the
4552       following individuals added to the list of Contributing Authors
4553
4554          Simon-Pierre Cadieux
4555          Eric S. Raymond
4556          Gilles Vollant
4557
4558       and with the following additions to the disclaimer:
4559
4560          There is no warranty against interference with your
4561          enjoyment of the library or against infringement.
4562          There is no warranty that our efforts or the library
4563          will fulfill any of your particular purposes or needs.
4564          This library is provided with all faults, and the entire
4565          risk of satisfactory quality, performance, accuracy, and
4566          effort is with the user.
4567
4568       libpng  versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
4569       Copyright (c) 1998, 1999 Glenn Randers-Pehrson Distributed according to
4570       the  same  disclaimer  and  license  as libpng-0.96, with the following
4571       individuals added to the list of Contributing Authors:
4572
4573          Tom Lane
4574          Glenn Randers-Pehrson
4575          Willem van Schaik
4576
4577       libpng versions 0.89, June 1996, through 0.96, May 1997, are  Copyright
4578       (c)  1996,  1997  Andreas Dilger Distributed according to the same dis‐
4579       claimer and license as  libpng-0.88,  with  the  following  individuals
4580       added to the list of Contributing Authors:
4581
4582          John Bowler
4583          Kevin Bracey
4584          Sam Bushell
4585          Magnus Holmgren
4586          Greg Roelofs
4587          Tom Tanner
4588
4589       libpng  versions  0.5,  May 1995, through 0.88, January 1996, are Copy‐
4590       right (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
4591
4592       For the purposes of this copyright and license, "Contributing  Authors"
4593       is defined as the following set of individuals:
4594
4595          Andreas Dilger
4596          Dave Martindale
4597          Guy Eric Schalnat
4598          Paul Schmidt
4599          Tim Wegner
4600
4601       The  PNG  Reference  Library  is  supplied  "AS  IS".  The Contributing
4602       Authors and Group  42,  Inc.  disclaim  all  warranties,  expressed  or
4603       implied, including, without limitation, the warranties of merchantabil‐
4604       ity and of fitness for any purpose.  The Contributing Authors and Group
4605       42,  Inc.   assume  no liability for direct, indirect, incidental, spe‐
4606       cial, exemplary, or consequential damages, which may  result  from  the
4607       use of the PNG Reference Library, even if advised of the possibility of
4608       such damage.
4609
4610       Permission is hereby granted to use, copy, modify, and distribute  this
4611       source  code, or portions hereof, for any purpose, without fee, subject
4612       to the following restrictions:
4613
4614       1. The origin of this source code must not be misrepresented.
4615
4616       2. Altered versions must be plainly marked as such and
4617          must not be misrepresented as being the original source.
4618
4619       3. This Copyright notice may not be removed or altered from
4620          any source or altered source distribution.
4621
4622       The Contributing Authors and Group 42, Inc. specifically permit,  with‐
4623       out  fee,  and  encourage the use of this source code as a component to
4624       supporting the PNG file format in commercial products.  If you use this
4625       source  code  in a product, acknowledgment is not required but would be
4626       appreciated.
4627
4628
4629       A "png_get_copyright" function is  available,  for  convenient  use  in
4630       "about" boxes and the like:
4631
4632          printf("%s",png_get_copyright(NULL));
4633
4634       Also,  the PNG logo (in PNG format, of course) is supplied in the files
4635       "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
4636
4637       Libpng is OSI Certified  Open  Source  Software.   OSI  Certified  Open
4638       Source is a certification mark of the Open Source Initiative.
4639
4640       Glenn Randers-Pehrson glennrp at users.sourceforge.net July 9, 2011
4641
4642
4643
4644
4645
4646                                 July 9, 2011                        LIBPNG(3)
Impressum