Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libpng / cc2770850ab788cc236513ada16ef2fe4cea7c71 / . / libpng.3
blob: 40b2e6c0dfe1daa3b76183e649018698fac3c4f0 [file] [log] [blame]
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]1.TH LIBPNG 3 "June 11, 2011"
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]2.SH NAME
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]3libpng \- Portable Network Graphics (PNG) Reference Library 1.5.3beta11
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4.SH SYNOPSIS
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]5\fI\fB
6
7\fB#include <png.h>\fP
8
9\fI\fB
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]10
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]11\fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP
12
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]13\fI\fB
14
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]15\fBvoid png_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
16
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]17\fI\fB
18
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]19\fBvoid png_build_grayscale_palette (int \fP\fIbit_depth\fP\fB, png_colorp \fIpalette\fP\fB);\fP
20
21\fI\fB
22
23\fBpng_voidp png_calloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
24
25\fI\fB
26
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]27\fBvoid png_chunk_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
28
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]29\fI\fB
30
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]31\fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]32
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]33\fI\fB
34
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]35\fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]36
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]37\fI\fB
38
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]39\fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]40
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]41\fI\fB
42
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]43\fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]44
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]45\fI\fB
46
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]47\fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]48
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]49\fI\fB
50
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]51\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]52
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]53\fI\fB
54
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]55\fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]56
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]57\fI\fB
58
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]59\fBpng_structp png_create_read_struct_2 (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]60
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]61\fI\fB
62
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]63\fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]64
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]65\fI\fB
66
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]67\fBpng_structp png_create_write_struct_2 (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
68
69\fI\fB
70
71\fBvoid png_data_freer (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIfreer\fP\fB, png_uint_32 \fImask)\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]72
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]73\fI\fB
74
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]75\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
76
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]77\fI\fB
78
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]79\fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP
80
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]81\fI\fB
82
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]83\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
84
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]85\fI\fB
86
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]87\fBvoid png_err (png_structp \fIpng_ptr\fP\fB);\fP
88
89\fI\fB
90
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]91\fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
92
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]93\fI\fB
94
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]95\fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
96
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]97\fI\fB
98
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]99\fBvoid png_free_chunk_list (png_structp \fIpng_ptr\fP\fB);\fP
100
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]101\fI\fB
102
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]103\fBvoid png_free_default (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]104
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]105\fI\fB
106
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]107\fBvoid png_free_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]108
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]109\fI\fB
110
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]111\fBpng_byte png_get_bit_depth (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]112
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]113\fI\fB
114
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]115\fBpng_uint_32 png_get_bKGD (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]116
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]117\fI\fB
118
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]119\fBpng_byte png_get_channels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]120
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]121\fI\fB
122
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]123\fBpng_uint_32 png_get_cHRM (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]124
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]125\fI\fB
126
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]127\fBpng_uint_32 png_get_cHRM_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]128
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]129\fI\fB
130
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]131\fBpng_uint_32 png_get_chunk_cache_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]132
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]133\fI\fB
134
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]135\fI\fB
136
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]137\fBpng_alloc_size_t png_get_chunk_malloc_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]138
139\fI\fB
140
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]141\fBpng_byte png_get_color_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]142
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]143\fI\fB
144
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]145\fBpng_uint_32 png_get_compression_buffer_size (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]146
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]147\fI\fB
148
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]149\fBpng_byte png_get_compression_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]150
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]151\fI\fB
152
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]153\fBpng_byte png_get_copyright (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]154
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]155\fI\fB
156
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]157\fBpng_uint_32 png_get_current_row_number \fI(png_const_structp\fP\fB);\fP
158
159\fI\fB
160
161\fBpng_byte png_get_current_pass_number \fI(png_const_structp\fP\fB);\fP
162
163\fI\fB
164
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]165\fBpng_voidp png_get_error_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]166
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]167\fI\fB
168
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]169\fBpng_byte png_get_filter_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]170
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]171\fI\fB
172
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]173\fBpng_uint_32 png_get_gAMA (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]174
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]175\fI\fB
176
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]177\fBpng_uint_32 png_get_gAMA_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]178
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]179\fI\fB
180
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]181\fBpng_byte png_get_header_ver (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]182
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]183\fI\fB
184
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]185\fBpng_byte png_get_header_version (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]186
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]187\fI\fB
188
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]189\fBpng_uint_32 png_get_hIST (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]190
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]191\fI\fB
192
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]193\fBpng_uint_32 png_get_iCCP (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_bytepp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]194
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]195\fI\fB
196
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]197\fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP
198
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]199\fI\fB
200
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]201\fBpng_uint_32 png_get_image_height (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]202
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]203\fI\fB
204
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]205\fBpng_uint_32 png_get_image_width (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]206
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]207\fI\fB
208
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]209\fBpng_int_32 png_get_int_32 (png_bytep \fIbuf\fP\fB);\fP
210
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]211\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]212
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]213\fBpng_byte png_get_interlace_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]214
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]215\fI\fB
216
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]217\fBpng_const_bytep png_get_io_chunk_name (png_structp \fIpng_ptr\fP\fB);\fP
218
219\fI\fB
220
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]221\fBpng_uint_32 png_get_io_chunk_type (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona63dbed2011-01-22 08:51:19 -0600[diff] [blame]222
223\fI\fB
224
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]225\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP
226
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]227\fI\fB
228
Glenn Randers-Pehrsona63dbed2011-01-22 08:51:19 -0600[diff] [blame]229\fBpng_uint_32 png_get_io_state (png_structp \fIpng_ptr\fP\fB);\fP
230
231\fI\fB
232
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]233\fBpng_byte png_get_libpng_ver (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]234
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]235\fI\fB
236
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]237\fBpng_voidp png_get_mem_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]238
239\fI\fB
240
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]241\fBpng_uint_32 png_get_oFFs (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]242
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]243\fI\fB
244
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]245\fBpng_uint_32 png_get_pCAL (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]246
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]247\fI\fB
248
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]249\fBpng_uint_32 png_get_pHYs (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]250
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]251\fI\fB
252
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]253\fBfloat png_get_pixel_aspect_ratio (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]254
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]255\fI\fB
256
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]257\fBpng_uint_32 png_get_pHYs_dpi (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]258
259\fI\fB
260
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]261\fBpng_fixed_point png_get_pixel_aspect_ratio_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]262
263\fI\fB
264
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]265\fBpng_uint_32 png_get_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]266
267\fI\fB
268
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]269\fBpng_uint_32 png_get_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]270
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]271\fI\fB
272
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]273\fBpng_voidp png_get_progressive_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]274
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]275\fI\fB
276
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]277\fBpng_uint_32 png_get_PLTE (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]278
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]279\fI\fB
280
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]281\fBpng_byte png_get_rgb_to_gray_status (png_const_structp \fIpng_ptr)
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]282
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]283\fBpng_uint_32 png_get_rowbytes (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]284
285\fI\fB
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]286
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]287\fBpng_bytepp png_get_rows (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]288
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]289\fI\fB
290
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]291\fBpng_uint_32 png_get_sBIT (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]292
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]293\fI\fB
294
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]295\fBvoid png_get_sCAL (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, double* \fP\fIwidth\fP\fB, double* \fIheight\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]296
297\fI\fB
298
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]299\fBvoid png_get_sCAL_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_fixed_pointp \fP\fIwidth\fP\fB, png_fixed_pointp \fIheight\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]300
301\fI\fB
302
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]303\fBvoid png_get_sCAL_s (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_charpp \fP\fIwidth\fP\fB, png_charpp \fIheight\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]304
305\fI\fB
306
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]307\fBpng_bytep png_get_signature (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]308
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]309\fI\fB
310
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]311\fBpng_uint_32 png_get_sPLT (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]312
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]313\fI\fB
314
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]315\fBpng_uint_32 png_get_sRGB (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int \fI*file_srgb_intent\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]316
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]317\fI\fB
318
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]319\fBpng_uint_32 png_get_text (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]320
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]321\fI\fB
322
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]323\fBpng_uint_32 png_get_tIME (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]324
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]325\fI\fB
326
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]327\fBpng_uint_32 png_get_tRNS (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans_alpha\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_color\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]328
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]329\fI\fB
330
331\fB/* This function is really an inline macro. \fI*/
332
333\fBpng_uint_16 png_get_uint_16 (png_bytep \fIbuf\fP\fB);\fP
334
335\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]336
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]337\fBpng_uint_32 png_get_uint_31 (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIbuf\fP\fB);\fP
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]338
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]339\fI\fB
340
341\fB/* This function is really an inline macro. \fI*/
342
343\fBpng_uint_32 png_get_uint_32 (png_bytep \fIbuf\fP\fB);\fP
344
345\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]346
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]347\fBpng_uint_32 png_get_unknown_chunks (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]348
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]349\fI\fB
350
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]351\fBpng_voidp png_get_user_chunk_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]352
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]353\fI\fB
354
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]355\fBpng_uint_32 png_get_user_height_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]356
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]357\fI\fB
358
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]359\fBpng_voidp png_get_user_transform_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]360
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]361\fI\fB
362
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]363\fBpng_uint_32 png_get_user_width_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]364
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]365\fI\fB
366
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]367\fBpng_uint_32 png_get_valid (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]368
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]369\fI\fB
370
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]371\fBfloat png_get_x_offset_inches (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]372
373\fI\fB
374
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]375\fBpng_fixed_point png_get_x_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]376
377\fI\fB
378
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]379\fBpng_int_32 png_get_x_offset_microns (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]380
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]381\fI\fB
382
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]383\fBpng_int_32 png_get_x_offset_pixels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]384
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]385\fI\fB
386
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]387\fBpng_uint_32 png_get_x_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]388
389\fI\fB
390
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]391\fBpng_uint_32 png_get_x_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]392
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]393\fI\fB
394
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]395\fBfloat png_get_y_offset_inches (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]396
397\fI\fB
398
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]399\fBpng_fixed_point png_get_y_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]400
401\fI\fB
402
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]403\fBpng_int_32 png_get_y_offset_microns (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]404
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]405\fI\fB
406
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]407\fBpng_int_32 png_get_y_offset_pixels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]408
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]409\fI\fB
410
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]411\fBpng_uint_32 png_get_y_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]412
413\fI\fB
414
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]415\fBpng_uint_32 png_get_y_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]416
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]417\fI\fB
418
Glenn Randers-Pehrsonc1bfe682002-03-06 22:08:00 -0600[diff] [blame]419\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP
420
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]421\fI\fB
422
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]423\fBvoid png_info_init_3 (png_infopp \fP\fIinfo_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP
424
425\fI\fB
426
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]427\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]428
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]429\fI\fB
430
Glenn Randers-Pehrsonf98726a2010-02-19 09:54:53 -0600[diff] [blame]431\fBvoid png_longjmp (png_structp \fP\fIpng_ptr\fP\fB, int \fIval\fP\fB);\fP
432
433\fI\fB
434
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]435\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]436
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]437\fI\fB
438
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]439\fBpng_voidp png_malloc_default (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
440
441\fI\fB
442
443\fBpng_voidp png_malloc_warn (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
444
445\fI\fB
446
447\fBpng_uint_32 png_permit_mng_features (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fImng_features_permitted\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]448
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]449\fI\fB
450
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]451\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP
452
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]453\fI\fB
454
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]455\fBpng_size_t png_process_data_pause \fP\fI(png_structp\fP\fB, int \fIsave\fP\fB);\fP
456
457\fI\fB
458
459\fBpng_uint_32 png_process_data_skip \fI(png_structp\fP\fB);\fP
460
461\fI\fB
462
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]463\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP
464
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]465\fI\fB
466
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]467\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
468
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]469\fI\fB
470
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]471\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
472
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]473\fI\fB
474
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]475\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
476
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]477\fI\fB
478
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]479\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]480
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]481\fI\fB
482
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]483\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
484
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]485\fI\fB
486
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]487\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
488
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]489\fI\fB
490
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]491\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
492
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]493\fI\fB
494
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]495\fBint png_reset_zstream (png_structp \fIpng_ptr\fP\fB);\fP
496
497\fI\fB
498
499\fBvoid png_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]500
501\fI\fB
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]502
503\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP
504
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]505\fI\fB
506
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]507\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP
508
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]509\fI\fB
510
511\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
512
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]513\fI\fB
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]514
Glenn Randers-Pehrsonc7822512011-05-07 21:23:43 -0500[diff] [blame]515\fBvoid png_set_alpha_mode (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, double \fIoutput_gamma\fP\fB);\fP
516
517\fI\fB
518
519\fBvoid png_set_alpha_mode_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, png_fixed_point \fIoutput_gamma\fP\fB);\fP
520
521\fI\fB
522
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]523\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP
524
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]525\fI\fB
526
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]527\fBvoid png_set_background_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, png_uint_32 \fIbackground_gamma\fP\fB);\fP
528
529\fI\fB
530
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]531\fBvoid png_set_benign_errors (png_structp \fP\fIpng_ptr\fP\fB, int \fIallowed\fP\fB);\fP
532
533\fI\fB
534
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]535\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP
536
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]537\fI\fB
538
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]539\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP
540
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]541\fI\fB
542
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]543\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB, double \fP\fIblue_x\fP\fB, double \fIblue_y\fP\fB);\fP
544
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]545\fI\fB
546
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]547\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\fB, png_uint_32 \fP\fIgreen_y\fP\fB, png_uint_32 \fP\fIblue_x\fP\fB, png_uint_32 \fIblue_y\fP\fB);\fP
548
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]549\fI\fB
550
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]551\fBvoid png_set_chunk_cache_max (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIuser_chunk_cache_max\fP\fB);\fP
552
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]553\fI\fB
554
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]555\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
556
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]557\fI\fB
558
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]559\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
560
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]561\fI\fB
562
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]563\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP
564
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]565\fI\fB
566
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]567\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]568
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]569\fI\fB
570
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]571\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]572
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]573\fI\fB
574
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]575\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]576
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]577\fI\fB
578
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]579\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]580
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]581\fI\fB
582
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]583\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsonc85f5f62011-02-13 05:56:07 -0600[diff] [blame]584
585\fI\fB
586
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]587\fBvoid png_set_expand_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]588
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]589\fI\fB
590
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]591\fBvoid png_set_expand_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]592
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]593\fI\fB
594
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]595\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]596
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]597\fI\fB
598
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]599\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]600
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]601\fI\fB
602
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]603\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]604
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]605\fI\fB
606
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]607\fBvoid png_set_filter_heuristics_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_fixed_point_p \fP\fIfilter_weights\fP\fB, png_fixed_point_p \fIfilter_costs\fP\fB);\fP
608
609\fI\fB
610
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]611\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]612
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]613\fI\fB
614
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]615\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]616
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]617\fI\fB
618
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]619\fBvoid png_set_gamma_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIscreen_gamma\fP\fB, png_uint_32 \fIdefault_file_gamma\fP\fB);\fP
620
621\fI\fB
622
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]623\fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]624
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]625\fI\fB
626
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]627\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP
628
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]629\fI\fB
630
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]631\fBvoid png_set_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]632
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]633\fI\fB
634
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]635\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]636
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]637\fI\fB
638
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]639\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]640
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]641\fI\fB
642
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]643\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_const_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_const_bytep \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]644
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]645\fI\fB
646
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]647\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]648
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]649\fI\fB
650
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]651\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP
652
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]653\fI\fB
654
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]655\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]656
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]657\fI\fB
658
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]659\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]660
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]661\fI\fB
662
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]663\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcompression_type\fP\fB, int \fIfilter_type\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]664
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]665\fI\fB
666
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]667\fBvoid png_set_keep_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIkeep\fP\fB, png_bytep \fP\fIchunk_list\fP\fB, int \fInum_chunks\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]668
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]669\fI\fB
670
Glenn Randers-Pehrson1e6ed732009-11-20 22:06:56 -0600[diff] [blame]671\fBjmp_buf* png_set_longjmp_fn (png_structp \fP\fIpng_ptr\fP\fB, png_longjmp_ptr \fP\fIlongjmp_fn\fP\fB, size_t \fIjmp_buf_size\fP\fB);\fP
672
673\fI\fB
674
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]675\fBvoid png_set_chunk_malloc_max (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIuser_chunk_cache_max\fP\fB);\fP
676
677\fI\fB
678
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]679\fBvoid png_set_compression_buffer_size (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
680
681\fI\fB
682
683\fBvoid png_set_mem_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]684
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]685\fI\fB
686
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]687\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]688
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]689\fI\fB
690
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]691\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]692
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]693\fI\fB
694
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]695\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]696
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]697\fI\fB
698
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]699\fBvoid png_set_palette_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]700
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]701\fI\fB
702
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]703\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, png_charpp \fIparams\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]704
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]705\fI\fB
706
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]707\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]708
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]709\fI\fB
710
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]711\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]712
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]713\fI\fB
714
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]715\fBvoid png_set_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fInum_palette\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]716
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]717\fI\fB
718
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]719\fBvoid png_set_quantize (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_quantize\fP\fB);\fP
720
721\fI\fB
722
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]723\fBvoid png_set_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fIread_data_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]724
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]725\fI\fB
726
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]727\fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]728
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]729\fI\fB
730
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]731\fBvoid png_set_read_user_chunk_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_chunk_ptr\fP\fB, png_user_chunk_ptr \fIread_user_chunk_fn\fP\fB);\fP
732
733\fI\fB
734
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]735\fBvoid png_set_read_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIread_user_transform_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]736
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]737\fI\fB
738
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]739\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP
740
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]741\fI\fB
742
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]743\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_uint_32 \fP\fIred\fP\fB, png_uint_32 \fIgreen\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]744
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]745\fI\fB
746
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]747\fBvoid png_set_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytepp \fIrow_pointers\fP\fB);\fP
748
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]749\fI\fB
750
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]751\fBvoid png_set_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fIsig_bit\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]752
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]753\fI\fB
754
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]755\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP
756
757\fI\fB
758
759\fBvoid png_set_sCAL_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_fixed_point \fP\fIwidth\fP\fB, png_fixed_point \fIheight\fP\fB);\fP
760
761\fI\fB
762
763\fBvoid png_set_sCAL_s (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_charp \fP\fIwidth\fP\fB, png_charp \fIheight\fP\fB);\fP
764
765\fI\fB
766
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]767\fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]768
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]769\fI\fB
770
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]771\fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]772
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]773\fI\fB
774
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]775\fBvoid png_set_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fIsplt_ptr\fP\fB, int \fInum_spalettes\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]776
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]777\fI\fB
778
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]779\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIsrgb_intent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]780
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]781\fI\fB
782
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]783\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIsrgb_intent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]784
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]785\fI\fB
786
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]787\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]788
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]789\fI\fB
790
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]791\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]792
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]793\fI\fB
794
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]795\fBvoid png_set_strip_error_numbers (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIstrip_mode\fP\fB);\fP
796
797\fI\fB
798
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]799\fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]800
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]801\fI\fB
802
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]803\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]804
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]805\fI\fB
806
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]807\fBvoid png_set_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fItext_ptr\fP\fB, int \fInum_text\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]808
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]809\fI\fB
810
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]811\fBvoid png_set_text_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
812
813\fI\fB
814
815\fBvoid png_set_text_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
816
817\fI\fB
818
819\fBvoid png_set_text_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
820
821\fI\fB
822
823\fBvoid png_set_text_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
824
825\fI\fB
826
827\fBvoid \fP\fIpng_set_text_compression_method\fP\fB, (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod)\fP\fB);\fP
828
829\fI\fB
830
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]831\fBvoid png_set_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fImod_time\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]832
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]833\fI\fB
834
Glenn Randers-Pehrsonf3c51e42011-01-15 10:25:25 -0600[diff] [blame]835\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans_alpha\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_color\fP\fB);\fP
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]836
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]837\fI\fB
838
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]839\fBvoid png_set_tRNS_to_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]840
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]841\fI\fB
842
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]843\fBpng_uint_32 png_set_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkp \fP\fIunknowns\fP\fB, int \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP
844
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]845\fI\fB
846
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]847\fBvoid png_set_unknown_chunk_location (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\fP\fB, int \fIlocation\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]848
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]849\fI\fB
850
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]851\fBvoid png_set_user_limits (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIuser_width_max\fP\fB, png_uint_32 \fIuser_height_max\fP\fB);\fP
852
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]853\fI\fB
854
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]855\fBvoid png_set_user_transform_info (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_transform_ptr\fP\fB, int \fP\fIuser_transform_depth\fP\fB, int \fIuser_transform_channels\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]856
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]857\fI\fB
858
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]859\fBvoid png_set_write_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fP\fIwrite_data_fn\fP\fB, png_flush_ptr \fIoutput_flush_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]860
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]861\fI\fB
862
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]863\fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]864
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]865\fI\fB
866
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]867\fBvoid png_set_write_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIwrite_user_transform_fn\fP\fB);\fP
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]868
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]869\fI\fB
870
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]871\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]872
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]873\fI\fB
874
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]875\fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]876
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]877\fI\fB
878
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]879\fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]880
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]881\fI\fB
882
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]883\fBvoid png_write_chunk (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]884
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]885\fI\fB
886
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]887\fBvoid png_write_chunk_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]888
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]889\fI\fB
890
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]891\fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]892
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]893\fI\fB
894
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]895\fBvoid png_write_chunk_start (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_uint_32 \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]896
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]897\fI\fB
898
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]899\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]900
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]901\fI\fB
902
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]903\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]904
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]905\fI\fB
906
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]907\fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]908
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]909\fI\fB
910
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]911\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]912
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]913\fI\fB
914
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]915\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
916
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]917\fI\fB
918
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]919\fBvoid png_write_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]920
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]921\fI\fB
922
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]923\fBvoid png_write_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIrow\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]924
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]925\fI\fB
926
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]927\fBvoid png_write_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]928
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]929\fI\fB
930
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]931\fBvoid png_write_sig (png_structp \fIpng_ptr\fP\fB);\fP
932
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]933\fI\fB
934
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]935\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP
936
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]937\fI\fB
938
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]939\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP
940
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]941\fI\fB
942
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]943.SH DESCRIPTION
944The
945.I libpng
946library supports encoding, decoding, and various manipulations of
947the Portable Network Graphics (PNG) format image files. It uses the
948.IR zlib(3)
949compression library.
Glenn Randers-Pehrson557b2562010-10-17 12:55:04 -0500[diff] [blame]950Following is a copy of the libpng-manual.txt file that accompanies libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]951.SH LIBPNG.TXT
Glenn Randers-Pehrson557b2562010-10-17 12:55:04 -0500[diff] [blame]952libpng-manual.txt - A description on how to use and modify libpng
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]953
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]954 libpng version 1.5.3beta11 - June 11, 2011
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]955 Updated and distributed by Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]956 <glennrp at users.sourceforge.net>
Glenn Randers-Pehrson9f45c8e2011-01-15 19:35:03 -0600[diff] [blame]957 Copyright (c) 1998-2011 Glenn Randers-Pehrson
Glenn Randers-Pehrson037023b2009-06-24 10:27:36 -0500[diff] [blame]958
Glenn Randers-Pehrsonbfbf8652009-06-26 21:46:52 -0500[diff] [blame]959 This document is released under the libpng license.
Glenn Randers-Pehrsonc332bbc2009-06-25 13:43:50 -0500[diff] [blame]960 For conditions of distribution and use, see the disclaimer
Glenn Randers-Pehrson037023b2009-06-24 10:27:36 -0500[diff] [blame]961 and license in png.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]962
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]963 Based on:
964
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]965 libpng versions 0.97, January 1998, through 1.5.3beta11 - June 11, 2011
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]966 Updated and distributed by Glenn Randers-Pehrson
Glenn Randers-Pehrson9f45c8e2011-01-15 19:35:03 -0600[diff] [blame]967 Copyright (c) 1998-2011 Glenn Randers-Pehrson
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]968
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]969 libpng 1.0 beta 6 version 0.96 May 28, 1997
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]970 Updated and distributed by Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]971 Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]972
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]973 libpng 1.0 beta 2 - version 0.88 January 26, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]974 For conditions of distribution and use, see copyright
975 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]976 Schalnat, Group 42, Inc.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]977
978 Updated/rewritten per request in the libpng FAQ
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]979 Copyright (c) 1995, 1996 Frank J. T. Wojcik
980 December 18, 1995 & January 20, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]981
982.SH I. Introduction
983
984This file describes how to use and modify the PNG reference library
985(known as libpng) for your own use. There are five sections to this
986file: introduction, structures, reading, writing, and modification and
987configuration notes for various special platforms. In addition to this
988file, example.c is a good starting point for using the library, as
989it is heavily commented and should include everything most people
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]990will need. We assume that libpng is already installed; see the
991INSTALL file for instructions on how to install libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]992
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]993For examples of libpng usage, see the files "example.c", "pngtest.c",
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]994and the files in the "contrib" directory, all of which are included in
995the libpng distribution.
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]997Libpng was written as a companion to the PNG specification, as a way
998of reducing the amount of time and effort it takes to support the PNG
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]999file format in application programs.
1000
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1001The PNG specification (second edition), November 2003, is available as
1002a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
1003<http://www.w3.org/TR/2003/REC-PNG-20031110/
1004The W3C and ISO documents have identical technical content.
1005
1006The PNG-1.2 specification is available at
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1007<http://www.libpng.org/pub/png/documents/>. It is technically equivalent
1008to the PNG specification (second edition) but has some additional material.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1009
1010The PNG-1.0 specification is available
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1011as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1012W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
1013
1014Some additional chunks are described in the special-purpose public chunks
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1015documents at <http://www.libpng.org/pub/png/documents/>.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1016
1017Other information
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1018about PNG, and the latest version of libpng, can be found at the PNG home
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1019page, <http://www.libpng.org/pub/png/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1020
1021Most users will not have to modify the library significantly; advanced
1022users may want to modify it more. All attempts were made to make it as
1023complete as possible, while keeping the code easy to understand.
1024Currently, this library only supports C. Support for other languages
1025is being considered.
1026
1027Libpng has been designed to handle multiple sessions at one time,
1028to be easily modifiable, to be portable to the vast majority of
1029machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
1030to use. The ultimate goal of libpng is to promote the acceptance of
1031the PNG file format in whatever way possible. While there is still
1032work to be done (see the TODO file), libpng should cover the
1033majority of the needs of its users.
1034
1035Libpng uses zlib for its compression and decompression of PNG files.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1036Further information about zlib, and the latest version of zlib, can
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]1037be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1038The zlib compression utility is a general purpose utility that is
1039useful for more than PNG files, and can be used without libpng.
1040See the documentation delivered with zlib for more details.
1041You can usually find the source files for the zlib utility wherever you
1042find the libpng source files.
1043
1044Libpng is thread safe, provided the threads are using different
1045instances of the structures. Each thread should have its own
1046png_struct and png_info instances, and thus its own image.
1047Libpng does not protect itself against two threads using the
Glenn Randers-Pehrson56f63962008-10-06 10:16:17 -0500[diff] [blame]1048same instance of a structure.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1049
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1050.SH II. Structures
1051
1052There are two main structures that are important to libpng, png_struct
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]1053and png_info. Both are internal structures that are no longer exposed
1054in the libpng interface (as of libpng 1.5.0).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1055
1056The png_info structure is designed to provide information about the
1057PNG file. At one time, the fields of png_info were intended to be
1058directly accessible to the user. However, this tended to cause problems
1059with applications using dynamically loaded libraries, and as a result
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]1060a set of interface functions for png_info (the png_get_*() and png_set_*()
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]1061functions) was developed.
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]1062
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]1063The png_struct structure is the object used by the library to decode a
1064single image. As of 1.5.0 this structure is also not exposed.
1065
1066Almost all libpng APIs require a pointer to a png_struct as the first argument.
1067Many (in particular the png_set and png_get APIs) also require a pointer
1068to png_info as the second argument. Some application visible macros
1069defined in png.h designed for basic data access (reading and writing
1070integers in the PNG format) break this rule, but it's almost always safe
1071to assume that a (png_struct*) has to be passed to call an API function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1072
1073The png.h header file is an invaluable reference for programming with libpng.
1074And while I'm on the topic, make sure you include the libpng header file:
1075
1076#include <png.h>
1077
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]1078.SS Types
1079
1080The png.h header file defines a number of integral types used by the
1081APIs. Most of these are fairly obvious; for example types corresponding
1082to integers of particular sizes and types for passing color values.
1083
1084One exception is how non-integral numbers are handled. For application
1085convenience most APIs that take such numbers have C (double) arguments,
1086however internally PNG, and libpng, use 32 bit signed integers and encode
1087the value by multiplying by 100,000. As of libpng 1.5.0 a convenience
1088macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
1089which is simply (png_int_32).
1090
1091All APIs that take (double) arguments also have an matching API that
1092takes the corresponding fixed point integer arguments. The fixed point
1093API has the same name as the floating point one with _fixed appended.
1094The actual range of values permitted in the APIs is frequently less than
1095the full range of (png_fixed_point) (-21474 to +21474). When APIs require
1096a non-negative argument the type is recorded as png_uint_32 above. Consult
1097the header file and the text below for more information.
1098
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]1099Special care must be take with sCAL chunk handling because the chunk itself
1100uses non-integral values encoded as strings containing decimal floating point
1101numbers. See the comments in the header file.
1102
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]1103.SS Configuration
1104
1105The main header file function declarations are frequently protected by C
1106preprocessing directives of the form:
1107
1108 #ifdef PNG_feature_SUPPORTED
1109 declare-function
1110 #endif
1111
1112The library can be built without support for these APIs, although a
1113standard build will have all implemented APIs. Application programs
1114should check the feature macros before using an API for maximum
1115portability. From libpng 1.5.0 the feature macros set during the build
1116of libpng are recorded in the header file "pnglibconf.h" and this file
1117is always included by png.h.
1118
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]1119If you don't need to change the library configuration from the default skip to
1120the next section ("Reading").
1121
1122Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
1123of the build project files in the 'projects' directory simply copy
1124scripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these build
1125systems do not permit easy auto-configuration of the library - they only
1126support the default configuration.
1127
1128The easiest way to make minor changes to the libpng configuration when
1129auto-configuration is supported is to add definitions to the command line
1130using (typically) CPPFLAGS. For example:
1131
1132CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
1133
1134will change the internal libpng math implementation for gamma correction and
1135other arithmetic calculations to fixed point, avoiding the need for fast
1136floating point support. The result can be seen in the generated pnglibconf.h -
1137make sure it contains the changed feature macro setting.
1138
1139If you need to make more extensive configuration changes - more than one or two
1140feature macro settings - you can either add -DPNG_USER_CONFIG to the build
1141command line and put a list of feature macro settings in pngusr.h or you can set
1142DFA_XTRA (a makefile variable) to a file containing the same information in the
1143form of 'option' settings.
1144
1145A. Changing pnglibconf.h
1146
1147A variety of methods exist to build libpng. Not all of these support
1148reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be
1149rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
1150
1151Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt and changing
1152the lines defining the supported features, paying very close attention to the
1153'option' information in scripts/pnglibconf.dfa that describes those features and
1154their requirements. This is easy to get wrong.
1155
1156B. Configuration using DFA_XTRA
1157
1158Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
1159variant such as 'nawk' or 'gawk', is available. The configure build will
1160automatically find an appropriate awk and build pnglibconf.h.
1161scripts/pnglibconf.mak contains a set of make rules for doing the same thing if
1162configure is not used, and many of the makefiles in the scripts directory use
1163this approach.
1164
1165When rebuilding simply write new file containing changed options and set
1166DFA_XTRA to the name of this file. This causes the build to append the new file
1167to the end of scripts/pnglibconf.dfa. pngusr.dfa should contain lines of the
1168following forms:
1169
1170everything = off
1171
1172This turns all optional features off. Include it at the start of pngusr.dfa to
1173make it easier to build a minimal configuration. You will need to turn at least
1174some features on afterward to enable either reading or writing code, or both.
1175
1176option feature on
1177option feature off
1178
1179Enable or disable a single feature. This will automatically enable other
1180features required by a feature that is turned on or disable other features that
1181require a feature which is turned off. Conflicting settings will cause an error
1182message to be emitted by awk.
1183
1184setting feature default value
1185
1186Changes the default value of setting 'feature' to 'value'. There are a small
1187number of settings listed at the top of pnglibconf.h, they are documented in the
1188source code. Most of these values have performance implications for the library
1189but most of them have no visible effect on the API. Some can also be overridden
1190from the API.
1191
1192C. Configuration using PNG_USR_CONFIG
1193
1194If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
1195pngusr.h will automatically be included before the options in
1196scripts/pnglibconf.dfa are processed. pngusr.h should contain only macro
1197definitions turning features on or off or setting settings.
1198
1199Apart from the global setting "everything = off" all the options listed above
1200can be set using macros in pngusr.h:
1201
1202#define PNG_feature_SUPPORTED
1203
1204is equivalent to:
1205
1206option feature on
1207
1208#define PNG_NO_feature
1209
1210is equivalent to:
1211
1212option feature off
1213
1214#define PNG_feature value
1215
1216is equivalent to:
1217
1218setting feature default value
1219
1220Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
1221pngusr file you supply override the contents of scripts/pnglibconf.dfa
1222
1223If confusing or incomprehensible behavior results it is possible to
1224examine the intermediate file pnglibconf.dfn to find the full set of
1225dependency information for each setting and option. Simply locate the
1226feature in the file and read the C comments that precede it.
1227
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1228.SH III. Reading
1229
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1230We'll now walk you through the possible functions to call when reading
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1231in a PNG file sequentially, briefly explaining the syntax and purpose
1232of each one. See example.c and png.h for more detail. While
1233progressive reading is covered in the next section, you will still
1234need some of the functions discussed in this section to read a PNG
1235file.
1236
1237.SS Setup
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1238
1239You will want to do the I/O initialization(*) before you get into libpng,
1240so if it doesn't work, you don't have much to undo. Of course, you
1241will also want to insure that you are, in fact, dealing with a PNG
1242file. Libpng provides a simple check to see if a file is a PNG file.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1243To use it, pass in the first 1 to 8 bytes of the file to the function
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]1244png_sig_cmp(), and it will return 0 (false) if the bytes match the
1245corresponding bytes of the PNG signature, or nonzero (true) otherwise.
1246Of course, the more bytes you pass in, the greater the accuracy of the
1247prediction.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1248
1249If you are intending to keep the file pointer open for use in libpng,
1250you must ensure you don't read more than 8 bytes from the beginning
1251of the file, and you also have to make a call to png_set_sig_bytes_read()
1252with the number of bytes you read from the beginning. Libpng will
1253then only check the bytes (if any) that your program didn't read.
1254
1255(*): If you are not using the standard I/O functions, you will need
1256to replace them with custom functions. See the discussion under
1257Customizing libpng.
1258
1259
1260 FILE *fp = fopen(file_name, "rb");
1261 if (!fp)
1262 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1263 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1264 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1265
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1266 fread(header, 1, number, fp);
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]1267 is_png = !png_sig_cmp(header, 0, number);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1268
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1269 if (!is_png)
1270 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1271 return (NOT_PNG);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1272 }
1273
1274
1275Next, png_struct and png_info need to be allocated and initialized. In
1276order to ensure that the size of these structures is correct even with a
1277dynamically linked libpng, there are functions to initialize and
1278allocate the structures. We also pass the library version, optional
1279pointers to error handling functions, and a pointer to a data struct for
1280use by the error functions, if necessary (the pointer and functions can
1281be NULL if the default error handlers are to be used). See the section
1282on Changes to Libpng below regarding the old initialization functions.
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1283The structure allocation functions quietly return NULL if they fail to
1284create the structure, so your application should check for that.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1285
1286 png_structp png_ptr = png_create_read_struct
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1287 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1288 user_error_fn, user_warning_fn);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1289
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1290 if (!png_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1291 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1292
1293 png_infop info_ptr = png_create_info_struct(png_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1294
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1295 if (!info_ptr)
1296 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1297 png_destroy_read_struct(&png_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1298 (png_infopp)NULL, (png_infopp)NULL);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1299 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1300 }
1301
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1302If you want to use your own memory allocation routines,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1303use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1304png_create_read_struct_2() instead of png_create_read_struct():
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1305
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1306 png_structp png_ptr = png_create_read_struct_2
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]1307 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1308 user_error_fn, user_warning_fn, (png_voidp)
1309 user_mem_ptr, user_malloc_fn, user_free_fn);
1310
1311The error handling routines passed to png_create_read_struct()
1312and the memory alloc/free routines passed to png_create_struct_2()
1313are only necessary if you are not using the libpng supplied error
1314handling and memory alloc/free functions.
1315
1316When libpng encounters an error, it expects to longjmp back
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1317to your routine. Therefore, you will need to call setjmp and pass
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1318your png_jmpbuf(png_ptr). If you read the file from different
John Bowlere6dc85b2011-04-27 14:47:15 -0500[diff] [blame]1319routines, you will need to update the longjmp buffer every time you enter
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1320a new routine that will call a png_*() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1321
1322See your documentation of setjmp/longjmp for your compiler for more
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1323information on setjmp/longjmp. See the discussion on libpng error
1324handling in the Customizing Libpng section below for more information
1325on the libpng error handling. If an error occurs, and libpng longjmp's
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1326back to your setjmp, you will want to call png_destroy_read_struct() to
1327free any memory.
1328
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1329 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1330 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1331 png_destroy_read_struct(&png_ptr, &info_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1332 &end_info);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1333 fclose(fp);
1334 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1335 }
1336
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]1337Pass (png_infopp)NULL instead of &end_info if you didn't create
1338an end_info structure.
1339
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1340If you would rather avoid the complexity of setjmp/longjmp issues,
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]1341you can compile libpng with PNG_NO_SETJMP, in which case
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1342errors will result in a call to PNG_ABORT() which defaults to abort().
1343
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]1344You can #define PNG_ABORT() to a function that does something
1345more useful than abort(), as long as your function does not
1346return.
1347
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1348Now you need to set up the input code. The default for libpng is to
1349use the C function fread(). If you use this, you will need to pass a
1350valid FILE * in the function png_init_io(). Be sure that the file is
1351opened in binary mode. If you wish to handle reading data in another
1352way, you need not call the png_init_io() function, but you must then
1353implement the libpng I/O methods discussed in the Customizing Libpng
1354section below.
1355
1356 png_init_io(png_ptr, fp);
1357
1358If you had previously opened the file and read any of the signature from
1359the beginning in order to see if this was a PNG file, you need to let
1360libpng know that there are some bytes missing from the start of the file.
1361
1362 png_set_sig_bytes(png_ptr, number);
1363
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]1364You can change the zlib compression buffer size to be used while
1365reading compressed data with
1366
1367 png_set_compression_buffer_size(png_ptr, buffer_size);
1368
1369where the default size is 8192 bytes. Note that the buffer size
1370is changed immediately and the buffer is reallocated immediately,
1371instead of setting a flag to be acted upon later.
1372
Glenn Randers-Pehrson9dd1cdf2011-01-06 21:42:36 -0600[diff] [blame]1373If you want CRC errors to be handled in a different manner than
1374the default, use
1375
1376 png_set_crc_action(png_ptr, crit_action, ancil_action);
1377
1378The values for png_set_crc_action() say how libpng is to handle CRC errors in
1379ancillary and critical chunks, and whether to use the data contained
1380therein. Note that it is impossible to "discard" data in a critical
1381chunk.
1382
1383Choices for (int) crit_action are
1384 PNG_CRC_DEFAULT 0 error/quit
1385 PNG_CRC_ERROR_QUIT 1 error/quit
1386 PNG_CRC_WARN_USE 3 warn/use data
1387 PNG_CRC_QUIET_USE 4 quiet/use data
1388 PNG_CRC_NO_CHANGE 5 use the current value
1389
1390Choices for (int) ancil_action are
1391 PNG_CRC_DEFAULT 0 error/quit
1392 PNG_CRC_ERROR_QUIT 1 error/quit
1393 PNG_CRC_WARN_DISCARD 2 warn/discard data
1394 PNG_CRC_WARN_USE 3 warn/use data
1395 PNG_CRC_QUIET_USE 4 quiet/use data
1396 PNG_CRC_NO_CHANGE 5 use the current value
1397
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1398.SS Setting up callback code
1399
1400You can set up a callback function to handle any unknown chunks in the
1401input stream. You must supply the function
1402
Glenn Randers-Pehrson81ce8892011-01-24 08:04:37 -0600[diff] [blame]1403 read_chunk_callback(png_structp png_ptr,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1404 png_unknown_chunkp chunk);
1405 {
1406 /* The unknown chunk structure contains your
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1407 chunk data, along with similar data for any other
1408 unknown chunks: */
1409
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1410 png_byte name[5];
1411 png_byte *data;
1412 png_size_t size;
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1413
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1414 /* Note that libpng has already taken care of
1415 the CRC handling */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1416
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1417 /* put your code here. Search for your chunk in the
1418 unknown chunk structure, process it, and return one
1419 of the following: */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1420
1421 return (-n); /* chunk had an error */
1422 return (0); /* did not recognize */
1423 return (n); /* success */
1424 }
1425
1426(You can give your function another name that you like instead of
1427"read_chunk_callback")
1428
1429To inform libpng about your function, use
1430
1431 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1432 read_chunk_callback);
1433
1434This names not only the callback function, but also a user pointer that
1435you can retrieve with
1436
1437 png_get_user_chunk_ptr(png_ptr);
1438
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1439If you call the png_set_read_user_chunk_fn() function, then all unknown
1440chunks will be saved when read, in case your callback function will need
1441one or more of them. This behavior can be changed with the
1442png_set_keep_unknown_chunks() function, described below.
1443
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1444At this point, you can set up a callback function that will be
1445called after each row has been read, which you can use to control
1446a progress meter or the like. It's demonstrated in pngtest.c.
1447You must supply a function
1448
Glenn Randers-Pehrson81ce8892011-01-24 08:04:37 -0600[diff] [blame]1449 void read_row_callback(png_structp png_ptr,
1450 png_uint_32 row, int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1451 {
1452 /* put your code here */
1453 }
1454
1455(You can give it another name that you like instead of "read_row_callback")
1456
1457To inform libpng about your function, use
1458
1459 png_set_read_status_fn(png_ptr, read_row_callback);
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1460
John Bowler59010e52011-02-16 06:16:31 -0600[diff] [blame]1461When this function is called the row has already been completely processed and
1462the 'row' and 'pass' refer to the next row to be handled. For the
1463non-interlaced case the row that was just handled is simply one less than the
1464passed in row number, and pass will always be 0. For the interlaced case the
1465same applies unless the row value is 0, in which case the row just handled was
1466the last one from one of the preceding passes. Because interlacing may skip a
1467pass you cannot be sure that the preceding pass is just 'pass-1', if you really
1468need to know what the last pass is record (row,pass) from the callback and use
1469the last recorded value each time.
1470
1471As with the user transform you can find the output row using the
1472PNG_ROW_FROM_PASS_ROW macro.
1473
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1474.SS Unknown-chunk handling
1475
1476Now you get to set the way the library processes unknown chunks in the
1477input PNG stream. Both known and unknown chunks will be read. Normal
1478behavior is that known chunks will be parsed into information in
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1479various info_ptr members while unknown chunks will be discarded. This
1480behavior can be wasteful if your application will never use some known
1481chunk types. To change this, you can call:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1482
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]1483 png_set_keep_unknown_chunks(png_ptr, keep,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1484 chunk_list, num_chunks);
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1485 keep - 0: default unknown chunk handling
1486 1: ignore; do not keep
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1487 2: keep only if safe-to-copy
1488 3: keep even if unsafe-to-copy
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1489
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1490 You can use these definitions:
1491 PNG_HANDLE_CHUNK_AS_DEFAULT 0
1492 PNG_HANDLE_CHUNK_NEVER 1
1493 PNG_HANDLE_CHUNK_IF_SAFE 2
1494 PNG_HANDLE_CHUNK_ALWAYS 3
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1495
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1496 chunk_list - list of chunks affected (a byte string,
1497 five bytes per chunk, NULL or '\0' if
1498 num_chunks is 0)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1499
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1500 num_chunks - number of chunks affected; if 0, all
Glenn Randers-Pehrsondff799e2004-08-07 21:42:49 -0500[diff] [blame]1501 unknown chunks are affected. If nonzero,
1502 only the chunks in the list are affected
1503
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1504Unknown chunks declared in this way will be saved as raw data onto a
1505list of png_unknown_chunk structures. If a chunk that is normally
1506known to libpng is named in the list, it will be handled as unknown,
1507according to the "keep" directive. If a chunk is named in successive
1508instances of png_set_keep_unknown_chunks(), the final instance will
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1509take precedence. The IHDR and IEND chunks should not be named in
1510chunk_list; if they are, libpng will process them normally anyway.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1511
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1512Here is an example of the usage of png_set_keep_unknown_chunks(),
1513where the private "vpAg" chunk will later be processed by a user chunk
1514callback function:
1515
1516 png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
1517
1518 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1519 png_byte unused_chunks[]=
1520 {
1521 104, 73, 83, 84, (png_byte) '\0', /* hIST */
1522 105, 84, 88, 116, (png_byte) '\0', /* iTXt */
1523 112, 67, 65, 76, (png_byte) '\0', /* pCAL */
1524 115, 67, 65, 76, (png_byte) '\0', /* sCAL */
1525 115, 80, 76, 84, (png_byte) '\0', /* sPLT */
1526 116, 73, 77, 69, (png_byte) '\0', /* tIME */
1527 };
1528 #endif
1529
1530 ...
1531
1532 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1533 /* ignore all unknown chunks: */
1534 png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1535
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1536 /* except for vpAg: */
1537 png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1538
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1539 /* also ignore unused known chunks: */
1540 png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
1541 (int)sizeof(unused_chunks)/5);
1542 #endif
1543
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]1544.SS User limits
1545
1546The PNG specification allows the width and height of an image to be as
1547large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1548Since very few applications really need to process such large images,
1549we have imposed an arbitrary 1-million limit on rows and columns.
1550Larger images will be rejected immediately with a png_error() call. If
Glenn Randers-Pehrsoncc277082011-06-10 21:17:34 -0500[diff] [blame^]1551you wish to reduce this limit, you can use
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]1552
1553 png_set_user_limits(png_ptr, width_max, height_max);
1554
1555to set your own limits, or use width_max = height_max = 0x7fffffffL
1556to allow all valid dimensions (libpng may reject some very large images
1557anyway because of potential buffer overflow conditions).
1558
1559You should put this statement after you create the PNG structure and
1560before calling png_read_info(), png_read_png(), or png_process_data().
Glenn Randers-Pehrsoncc277082011-06-10 21:17:34 -0500[diff] [blame^]1561
1562When writing a PNG datastream, put this statement before calling
1563png_write_info() or png_write_png().
1564
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]1565If you need to retrieve the limits that are being applied, use
1566
1567 width_max = png_get_user_width_max(png_ptr);
1568 height_max = png_get_user_height_max(png_ptr);
1569
1570The PNG specification sets no limit on the number of ancillary chunks
1571allowed in a PNG datastream. You can impose a limit on the total number
1572of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
1573
1574 png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
1575
1576where 0x7fffffffL means unlimited. You can retrieve this limit with
1577
1578 chunk_cache_max = png_get_chunk_cache_max(png_ptr);
1579
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]1580This limit also applies to the number of buffers that can be allocated
1581by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
1582
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]1583You can also set a limit on the amount of memory that a compressed chunk
1584other than IDAT can occupy, with
1585
1586 png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
1587
1588and you can retrieve the limit with
1589
1590 chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
1591
1592Any chunks that would cause either of these limits to be exceeded will
1593be ignored.
1594
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1595.SS Information about your system
1596
1597If you intend to display the PNG or to incorporate it in other image data you
1598need to tell libpng information about your display or drawing surface so that
1599libpng can convert the values in the image to match the display.
1600
1601From libpng-1.5.3 this information can be set before reading the PNG file
1602header. In earlier versions png_set_gamma() existed but behaved incorrectly if
1603called before the PNG file header had been read and png_set_alpha_mode() did not
1604exist.
1605
1606If you need to support versions prior to libpng-1.5.3 test the version number
1607and follow the procedures described in the appropriate manual page.
1608
1609You give libpng the encoding expected by your system expressed as a 'gamma'
1610value. You can also specify a default encoding for the PNG file in
1611case the required information is missing from the file. By default libpng
1612assumes that the PNG data matches your system, to keep this default call:
1613
1614 png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
1615
1616or you can use the fixed point equivalent:
1617
1618 png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_gamma);
1619
1620If you don't know the gamma for you system it is probably 2.2 - a good
1621approximation to the IEC standard for display systems (sRGB). If images are
1622too contrasty or washed out you got the value wrong - check your system
1623documentation!
1624
1625Many systems permit the system gamma to be changed via a lookup table in the
1626display driver, a few systems, including older Macs, change the response by
1627default. As of 1.5.3 three special values are available to handle common
1628situations:
1629
1630 PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
1631 standard. This matches almost all systems.
1632 PNG_GAMMA_MAC_18: Indicates that the system is an older (pre Mac OS 10.6)
1633 Apple Macintosh system with the default settings.
1634 PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates that the
1635 system expects data with no gamma encoding.
1636
1637You would use the linear (unencoded) value if you need to process the pixel
1638values further because this avoids the need to decode and reencode each
1639component value whenever arithmetic is performed. A lot of graphics software
1640uses linear values for this reason, often with higher precision component values
1641to preserve overall accuracy.
1642
1643The second thing you may need to tell libpng about is how your system handles
1644alpha channel information. Some, but not all, PNG files contain an alpha
1645channel. To display these files correctly you need to compose the data onto a
1646suitable background, as described in the PNG specification.
1647
1648Libpng only supports composing onto a single color (using png_set_background;
1649see below.) Otherwise you must do the composition yourself and, in this case,
1650you may need to call png_set_alpha_mode:
1651
1652 png_set_alpha_mode(png_ptr, mode, screen_gamma);
1653
1654The screen_gamma value is the same as the argument to png_set_gamma, however how
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1655it affects the output depends on the mode. png_set_alpha_mode() sets the file
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1656gamma default to 1/screen_gamma, so normally you don't need to call
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1657png_set_gamma. If you need different defaults call png_set_gamma() before
1658png_set_alpha_mode() - if you call it after it will override the settings made
1659by png_set_alpha_mode().
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1660
1661The mode is as follows:
1662
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1663 PNG_ALPHA_PNG: The data is encoded according to the PNG specification. Red,
1664green and blue, or gray, components are gamma encoded color
1665values and are not premultiplied by the alpha value. The
1666alpha value is a linear measure of the contribution of the
1667pixel to the corresponding final output pixel.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1668
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1669You should normally use this format if you intend to perform
1670color correction on the color values; most, maybe all, color
1671correction software has no handling for the alpha channel and,
1672anyway, the math to handle pre-multiplied component values is
1673unnecessarily complex.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1674
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1675Before you do any arithmetic on the component values you need
1676to remove the gamma encoding and multiply out the alpha
1677channel. See the PNG specification for more detail. It is
1678important to note that when an image with an alpha channel is
1679scaled, linear encoded, pre-multiplied component values must
1680be used!
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1681
1682The remaining modes assume you don't need to do any further color correction or
1683that if you do your color correction software knows all about alpha (it
1684probably doesn't!)
1685
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1686 PNG_ALPHA_STANDARD: The data libpng produces is encoded in the standard way
1687assumed by most correctly written graphics software.
1688The gamma encoding will be removed by libpng and the
1689linear component values will be pre-multiplied by the
1690alpha channel.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1691
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1692With this format the final image must be re-encoded to
1693match the display gamma before the image is displayed.
1694If your system doesn't do that, yet still seems to
1695perform arithmetic on the pixels without decoding them,
1696it is broken - check out the modes below.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1697
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1698With PNG_ALPHA_STANDARD libpng always produces linear
1699component values, whatever screen_gamma you supply. The
1700screen_gamma value is, however, used as a default for
1701the file gamma if the PNG file has no gamma information.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1702
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1703If you call png_set_gamma() after png_set_alpha_mode() you
1704will override the linear encoding. Instead the
1705pre-multiplied pixel values will be gamma encoded but
1706the alpha channel will still be linear. This may
1707actually match the requirements of some broken software,
1708but it is unlikely.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1709
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1710While linear 8-bit data is often used it has
1711insufficient precision for any image with a reasonable
1712dynamic range. To avoid problems, and if your software
1713supports it, use png_set_expand_16() to force all
1714components to 16 bits.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1715
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1716 PNG_ALPHA_OPTIMIZED: This mode is the same as PNG_ALPHA_STANDARD except that
1717completely opaque pixels are gamma encoded according to
1718the screen_gamma value. Pixels with alpha less than 1.0
1719will still have linear components.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1720
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1721Use this format if you have control over your
1722compositing software and do don't do other arithmetic
1723(such as scaling) on the data you get from libpng. Your
1724compositing software can simply copy opaque pixels to
1725the output but still has linear values for the
1726non-opaque pixels.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1727
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1728In normal compositing, where the alpha channel encodes
1729partial pixel coverage (as opposed to broad area
1730translucency), the inaccuracies of the 8-bit
1731representation of non-opaque pixels are irrelevant.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1732
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1733You can also try this format if your software is broken;
1734it might look better.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1735
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1736 PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD however all component values,
1737including the alpha channel are gamma encoded. This is
1738an appropriate format to try if your software, or more
1739likely hardware, is totally broken: if it performs
1740linear arithmetic directly on gamma encoded values.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1741
1742In most cases of broken software or hardware the bug in the final display
1743manifests as a subtle halo around composited parts of the image. You may not
1744even perceive this as a halo; the composited part of the image may simply appear
1745separate from the background, as though it had been cut out of paper and pasted
1746on afterward.
1747
1748If you don't have to deal with bugs in software or hardware, or if you can fix
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1749them, there are three recommended ways of using png_set_alpha_mode():
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1750
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1751 png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
1752 screen_gamma);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1753
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1754You can do color correction on the result (libpng does not currently
1755support color correction internally.) When you handle the alpha channel
1756you need to undo the gamma encoding and multiply out the alpha.
1757
1758 png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
1759 screen_gamma);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1760 png_set_expand_16(png_ptr);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1761
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1762If you are using the high level interface don't call png_set_expand_16();
1763instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1764
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1765With this mode you can't do color correction, but you can do arithmetic,
1766including composition and scaling, on the data without further processing.
1767
1768 png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
1769 screen_gamma);
1770
1771You can avoid the expansion to 16-bit components with this mode, but you
1772lose the ability to scale the image or perform other linear arithmetic.
1773All you can do is compose the result onto a matching output. Since this
1774mode is libpng specific you also need to write your own composition
1775software.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1776
1777If you don't need, or can't handle, the alpha channel you can call
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1778png_set_background() to remove it by compositing against a fixed color. Don't
1779call png_set_strip_alpha() to do this - it will leave spurious pixel values in
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1780transparent parts of this image.
1781
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1782 png_set_background(png_ptr, &background_color,
1783 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1784
1785The background_color is an RGB or grayscale value according to the data format
1786libpng will produce for you. Because you don't yet know the format of the PNG
1787file if you call png_set_background at this point you must arrange for the
1788format produced by libpng to always have 8-bit or 16-bit components and then
1789store the color as an 8-bit or 16-bit color as appropriate. The color contains
1790separate gray and RGB component values, so you can let libpng produce gray or
1791RGB output according to the input format, but low bit depth grayscale images
1792must always be converted to at least 8-bit format. (Even low low bit depth
1793grayscale images can't have an alpha channel they can have a transparent
1794color!)
1795
1796You set the transforms you need later, either as flags to the high level
1797interface or libpng API calls for the low level interface. For reference the
1798settings required are:
1799
18008-bit values:
1801 PNG_TRANSFORM_STRIP_16 | PNG_EXPAND
1802 png_set_expand(png_ptr); png_set_strip_16(png_ptr);
1803
180416-bit values:
1805 PNG_TRANSFORM_EXPAND_16
1806 png_set_expand_16(png_ptr);
1807
1808In either case palette image data will be expanded to RGB. If you just want
1809color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
1810to the list.
1811
1812Calling png_set_background before the PNG file header is read will not work
1813prior to libpng-1.5.3. Because the failure may result in unexpected warnings or
1814errors it is therefore much safer to call png_set_background after the head has
1815been read. Unfortunately this means that prior to libpng-1.5.3 it cannot be
1816used with the high level interface.
1817
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1818.SS The high-level read interface
1819
1820At this point there are two ways to proceed; through the high-level
1821read interface, or through a sequence of low-level read operations.
1822You can use the high-level interface if (a) you are willing to read
1823the entire image into memory, and (b) the input transformations
1824you want to do are limited to the following set:
1825
1826 PNG_TRANSFORM_IDENTITY No transformation
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1827 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1828 8-bit
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1829 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1830 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
1831 samples to bytes
1832 PNG_TRANSFORM_PACKSWAP Change order of packed
1833 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1834 PNG_TRANSFORM_EXPAND Perform set_expand()
1835 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1836 PNG_TRANSFORM_SHIFT Normalize pixels to the
1837 sBIT depth
1838 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
1839 to BGRA
1840 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
1841 to AG
1842 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
1843 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1844 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
Glenn Randers-Pehrson99708d52009-06-29 17:30:00 -0500[diff] [blame]1845 PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
1846 to RGB (or GA to RGBA)
John Bowlera9b34192011-05-08 19:46:51 -0500[diff] [blame]1847 PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1848
1849(This excludes setting a background color, doing gamma transformation,
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]1850quantizing, and setting filler.) If this is the case, simply do this:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1851
1852 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1853
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]1854where png_transforms is an integer containing the bitwise OR of some
1855set of transformation flags. This call is equivalent to png_read_info(),
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1856followed the set of transformations indicated by the transform mask,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1857then png_read_image(), and finally png_read_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1858
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1859(The final parameter of this call is not yet used. Someday it might point
1860to transformation parameters required by some future input transform.)
1861
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1862You must use png_transforms and not call any png_set_transform() functions
1863when you use png_read_png().
1864
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1865After you have called png_read_png(), you can retrieve the image data
1866with
1867
1868 row_pointers = png_get_rows(png_ptr, info_ptr);
1869
1870where row_pointers is an array of pointers to the pixel data for each row:
1871
1872 png_bytep row_pointers[height];
1873
1874If you know your image size and pixel size ahead of time, you can allocate
1875row_pointers prior to calling png_read_png() with
1876
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1877 if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]1878 png_error (png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1879 "Image is too tall to process in memory");
1880
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]1881 if (width > PNG_UINT_32_MAX/pixel_size)
1882 png_error (png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1883 "Image is too wide to process in memory");
1884
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1885 row_pointers = png_malloc(png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1886 height*png_sizeof(png_bytep));
1887
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1888 for (int i=0; i<height, i++)
1889 row_pointers[i]=NULL; /* security precaution */
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1890
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1891 for (int i=0; i<height, i++)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1892 row_pointers[i]=png_malloc(png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1893 width*pixel_size);
1894
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]1895 png_set_rows(png_ptr, info_ptr, &row_pointers);
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1896
1897Alternatively you could allocate your image in one big block and define
1898row_pointers[i] to point into the proper places in your block.
1899
1900If you use png_set_rows(), the application is responsible for freeing
1901row_pointers (and row_pointers[i], if they were separately allocated).
1902
1903If you don't allocate row_pointers ahead of time, png_read_png() will
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1904do it, and it'll be free'ed by libpng when you call png_destroy_*().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1905
1906.SS The low-level read interface
1907
1908If you are going the low-level route, you are now ready to read all
1909the file information up to the actual image data. You do this with a
1910call to png_read_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1911
1912 png_read_info(png_ptr, info_ptr);
1913
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1914This will process all chunks up to but not including the image data.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1915
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1916This also copies some of the data from the PNG file into the decode structure
1917for use in later transformations. Important information copied in is:
1918
19191) The PNG file gamma from the gAMA chunk. This overwrites the default value
1920provided by an earlier call to png_set_gamma or png_set_alpha_mode.
1921
19222) Prior to libpng-1.5.3 the background color from a bKGd chunk. This
1923damages the information provided by an earlier call to png_set_background
1924resulting in expected behavior. Libpng-1.5.3 no longer does this.
1925
19263) The number of significant bits in each component value. Libpng uses this to
1927optimize gamma handling by reducing the internal lookup table sizes.
1928
19294) The transparent color information from a tRNS chunk. This can be modified by
1930a later call to png_set_tRNS.
1931
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1932.SS Querying the info structure
1933
1934Functions are used to get the information from the info_ptr once it
1935has been read. Note that these fields may not be completely filled
1936in until png_read_end() has read the chunk data following the image.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1937
1938 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1939 &bit_depth, &color_type, &interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1940 &compression_type, &filter_method);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1941
1942 width - holds the width of the image
1943 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1944
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1945 height - holds the height of the image
1946 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1947
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1948 bit_depth - holds the bit depth of one of the
1949 image channels. (valid values are
1950 1, 2, 4, 8, 16 and depend also on
1951 the color_type. See also
1952 significant bits (sBIT) below).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1953
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1954 color_type - describes which color/alpha channels
1955 are present.
1956 PNG_COLOR_TYPE_GRAY
1957 (bit depths 1, 2, 4, 8, 16)
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1958 PNG_COLOR_TYPE_GRAY_ALPHA
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1959 (bit depths 8, 16)
1960 PNG_COLOR_TYPE_PALETTE
1961 (bit depths 1, 2, 4, 8)
1962 PNG_COLOR_TYPE_RGB
1963 (bit_depths 8, 16)
1964 PNG_COLOR_TYPE_RGB_ALPHA
1965 (bit_depths 8, 16)
1966
1967 PNG_COLOR_MASK_PALETTE
1968 PNG_COLOR_MASK_COLOR
1969 PNG_COLOR_MASK_ALPHA
1970
Glenn Randers-Pehrson2cb633b2011-01-21 08:31:29 -0600[diff] [blame]1971 interlace_type - (PNG_INTERLACE_NONE or
1972 PNG_INTERLACE_ADAM7)
1973
1974 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1975 for PNG 1.0)
1976
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1977 filter_method - (must be PNG_FILTER_TYPE_BASE
1978 for PNG 1.0, and can also be
1979 PNG_INTRAPIXEL_DIFFERENCING if
1980 the PNG datastream is embedded in
1981 a MNG-1.0 datastream)
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1982
1983 Any or all of interlace_type, compression_type, or
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1984 filter_method can be NULL if you are
1985 not interested in their values.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1986
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1987 Note that png_get_IHDR() returns 32-bit data into
1988 the application's width and height variables.
1989 This is an unsafe situation if these are 16-bit
1990 variables. In such situations, the
1991 png_get_image_width() and png_get_image_height()
1992 functions described below are safer.
1993
1994 width = png_get_image_width(png_ptr,
1995 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1996
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1997 height = png_get_image_height(png_ptr,
1998 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1999
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]2000 bit_depth = png_get_bit_depth(png_ptr,
2001 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2002
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]2003 color_type = png_get_color_type(png_ptr,
2004 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2005
Glenn Randers-Pehrson2cb633b2011-01-21 08:31:29 -0600[diff] [blame]2006 interlace_type = png_get_interlace_type(png_ptr,
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]2007 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2008
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]2009 compression_type = png_get_compression_type(png_ptr,
2010 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2011
Glenn Randers-Pehrson2cb633b2011-01-21 08:31:29 -0600[diff] [blame]2012 filter_method = png_get_filter_type(png_ptr,
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]2013 info_ptr);
2014
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2015 channels = png_get_channels(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2016
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2017 channels - number of channels of info for the
2018 color type (valid values are 1 (GRAY,
2019 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
2020 4 (RGB_ALPHA or RGB + filler byte))
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2021
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2022 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2023
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2024 rowbytes - number of bytes needed to hold a row
2025
2026 signature = png_get_signature(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2027
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2028 signature - holds the signature read from the
2029 file (if any). The data is kept in
2030 the same offset it would be if the
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2031 whole signature were read (i.e. if an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2032 application had already read in 4
2033 bytes of signature before starting
2034 libpng, the remaining 4 bytes would
2035 be in signature[4] through signature[7]
2036 (see png_set_sig_bytes())).
2037
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2038These are also important, but their validity depends on whether the chunk
2039has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
2040png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
2041data has been read, or zero if it is missing. The parameters to the
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]2042png_get_<chunk> are set directly if they are simple data types, or a
2043pointer into the info_ptr is returned for any complex types.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2044
2045 png_get_PLTE(png_ptr, info_ptr, &palette,
2046 &num_palette);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2047
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2048 palette - the palette for the file
2049 (array of png_color)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2050
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2051 num_palette - number of entries in the palette
2052
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]2053 png_get_gAMA(png_ptr, info_ptr, &file_gamma);
Glenn Randers-Pehrson27742382011-01-27 09:37:34 -0600[diff] [blame]2054 png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2055
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]2056 file_gamma - the gamma at which the file is
2057 written (PNG_INFO_gAMA)
2058
2059 int_file_gamma - 100,000 times the gamma at which the
2060 file is written
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2061
2062 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2063
Glenn Randers-Pehrson27742382011-01-27 09:37:34 -0600[diff] [blame]2064 file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2065 The presence of the sRGB chunk
2066 means that the pixel data is in the
2067 sRGB color space. This chunk also
2068 implies specific values of gAMA and
2069 cHRM.
2070
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2071 png_get_iCCP(png_ptr, info_ptr, &name,
2072 &compression_type, &profile, &proflen);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2073
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]2074 name - The profile name.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2075
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]2076 compression_type - The compression type; always
2077 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2078 You may give NULL to this argument to
2079 ignore it.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2080
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]2081 profile - International Color Consortium color
2082 profile data. May contain NULs.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2083
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]2084 proflen - length of profile data in bytes.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2085
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2086 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2087
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2088 sig_bit - the number of significant bits for
2089 (PNG_INFO_sBIT) each of the gray,
2090 red, green, and blue channels,
2091 whichever are appropriate for the
2092 given color type (png_color_16)
2093
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]2094 png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
2095 &num_trans, &trans_color);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2096
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]2097 trans_alpha - array of alpha (transparency)
2098 entries for palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2099
Glenn Randers-Pehrsonf3c51e42011-01-15 10:25:25 -0600[diff] [blame]2100 num_trans - number of transparent entries
2101 (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2102
Glenn Randers-Pehrson56f63962008-10-06 10:16:17 -0500[diff] [blame]2103 trans_color - graylevel or color sample values of
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]2104 the single transparent color for
2105 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2106
2107 png_get_hIST(png_ptr, info_ptr, &hist);
2108 (PNG_INFO_hIST)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2109
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2110 hist - histogram of palette (array of
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2111 png_uint_16)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2112
2113 png_get_tIME(png_ptr, info_ptr, &mod_time);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2114
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2115 mod_time - time image was last modified
2116 (PNG_VALID_tIME)
2117
2118 png_get_bKGD(png_ptr, info_ptr, &background);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2119
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2120 background - background color (PNG_VALID_bKGD)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2121 valid 16-bit red, green and blue
2122 values, regardless of color_type
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2123
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2124 num_comments = png_get_text(png_ptr, info_ptr,
2125 &text_ptr, &num_text);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2126
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2127 num_comments - number of comments
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2128
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2129 text_ptr - array of png_text holding image
2130 comments
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2131
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2132 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2133 on "text" PNG_TEXT_COMPRESSION_NONE
2134 PNG_TEXT_COMPRESSION_zTXt
2135 PNG_ITXT_COMPRESSION_NONE
2136 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2137
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2138 text_ptr[i].key - keyword for comment. Must contain
2139 1-79 characters.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2140
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2141 text_ptr[i].text - text comments for current
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2142 keyword. Can be empty.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2143
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2144 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2145 after decompression, 0 for iTXt
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2146
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2147 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2148 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2149
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2150 text_ptr[i].lang - language of comment (empty
2151 string for unknown).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2152
Glenn Randers-Pehrson73d57cb2002-03-25 18:49:08 -0600[diff] [blame]2153 text_ptr[i].lang_key - keyword in UTF-8
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2154 (empty string for unknown).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2155
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]2156 Note that the itxt_length, lang, and lang_key
2157 members of the text_ptr structure only exist
2158 when the library is built with iTXt chunk support.
2159
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2160 num_text - number of comments (same as
2161 num_comments; you can put NULL here
2162 to avoid the duplication)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2163
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2164 Note while png_set_text() will accept text, language,
2165 and translated keywords that can be NULL pointers, the
2166 structure returned by png_get_text will always contain
2167 regular zero-terminated C strings. They might be
2168 empty strings but they will never be NULL pointers.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2169
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2170 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
2171 &palette_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2172
2173 num_spalettes - number of sPLT chunks read.
2174
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2175 palette_ptr - array of palette structures holding
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2176 contents of one or more sPLT chunks
2177 read.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2178
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2179 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2180 &unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2181
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2182 offset_x - positive offset from the left edge
2183 of the screen
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2184
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2185 offset_y - positive offset from the top edge
2186 of the screen
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2187
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2188 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2189
2190 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2191 &unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2192
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2193 res_x - pixels/unit physical resolution in
2194 x direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2195
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2196 res_y - pixels/unit physical resolution in
2197 x direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2198
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2199 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2200 PNG_RESOLUTION_METER
2201
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2202 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
2203 &height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2204
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2205 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2206
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2207 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2208
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2209 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2210 (width and height are doubles)
2211
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2212 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
2213 &height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2214
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2215 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2216
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2217 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2218
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2219 height - height of a pixel in physical scale units
2220 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2221
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2222 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
2223 info_ptr, &unknowns)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2224
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2225 unknowns - array of png_unknown_chunk
2226 structures holding unknown chunks
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2227
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2228 unknowns[i].name - name of unknown chunk
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2229
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2230 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2231
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2232 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2233
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2234 unknowns[i].location - position of chunk in file
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2235
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2236 The value of "i" corresponds to the order in which the
2237 chunks were read from the PNG file or inserted with the
2238 png_set_unknown_chunks() function.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2239
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2240The data from the pHYs chunk can be retrieved in several convenient
2241forms:
2242
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2243 res_x = png_get_x_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2244 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2245
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2246 res_y = png_get_y_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2247 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2248
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2249 res_x_and_y = png_get_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2250 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2251
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2252 res_x = png_get_x_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2253 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2254
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2255 res_y = png_get_y_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2256 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2257
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2258 res_x_and_y = png_get_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2259 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2260
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2261 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2262 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2263
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2264 Each of these returns 0 [signifying "unknown"] if
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2265 the data is not present or if res_x is 0;
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2266 res_x_and_y is 0 if res_x != res_y
2267
2268 Note that because of the way the resolutions are
2269 stored internally, the inch conversions won't
2270 come out to exactly even number. For example,
2271 72 dpi is stored as 0.28346 pixels/meter, and
2272 when this is retrieved it is 71.9988 dpi, so
2273 be sure to round the returned value appropriately
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2274 if you want to display a reasonable-looking result.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2275
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2276The data from the oFFs chunk can be retrieved in several convenient
2277forms:
2278
2279 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2280
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2281 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2282
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2283 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2284
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2285 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
2286
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2287 Each of these returns 0 [signifying "unknown" if both
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2288 x and y are 0] if the data is not present or if the
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2289 chunk is present but the unit is the pixel. The
2290 remark about inexact inch conversions applies here
2291 as well, because a value in inches can't always be
2292 converted to microns and back without some loss
2293 of precision.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2294
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2295For more information, see the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2296PNG specification for chunk contents. Be careful with trusting
2297rowbytes, as some of the transformations could increase the space
2298needed to hold a row (expand, filler, gray_to_rgb, etc.).
2299See png_read_update_info(), below.
2300
2301A quick word about text_ptr and num_text. PNG stores comments in
2302keyword/text pairs, one pair per chunk, with no limit on the number
2303of text chunks, and a 2^31 byte limit on their size. While there are
2304suggested keywords, there is no requirement to restrict the use to these
2305strings. It is strongly suggested that keywords and text be sensible
2306to humans (that's the point), so don't use abbreviations. Non-printing
2307symbols are not allowed. See the PNG specification for more details.
2308There is also no requirement to have text after the keyword.
2309
2310Keywords should be limited to 79 Latin-1 characters without leading or
2311trailing spaces, but non-consecutive spaces are allowed within the
2312keyword. It is possible to have the same keyword any number of times.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2313The text_ptr is an array of png_text structures, each holding a
2314pointer to a language string, a pointer to a keyword and a pointer to
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2315a text string. The text string, language code, and translated
2316keyword may be empty or NULL pointers. The keyword/text
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2317pairs are put into the array in the order that they are received.
2318However, some or all of the text chunks may be after the image, so, to
2319make sure you have read all the text chunks, don't mess with these
2320until after you read the stuff after the image. This will be
2321mentioned again below in the discussion that goes with png_read_end().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2322
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2323.SS Input transformations
2324
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2325After you've read the header information, you can set up the library
2326to handle any special transformations of the image data. The various
2327ways to transform the data will be described in the order that they
2328should occur. This is important, as some of these change the color
2329type and/or bit depth of the data, and some others only work on
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2330certain color types and bit depths.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2331
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2332Transformations you request are ignored if they don't have any meaning for a
2333particular input data format. However some transformations can have an effect
2334as a result of a previous transformation. If you specify a contradictory set of
2335transformations, for example both adding and removing the alpha channel, you
2336cannot predict the final result.
2337
2338The color used for the transparency values should be supplied in the same
2339format/depth as the current image data. It is stored in the same format/depth
2340as the image data in a tRNS chunk, so this is what libpng expects for this data.
2341
2342The color used for the background value depends on the need_expand argument as
2343described below.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2344
2345Data will be decoded into the supplied row buffers packed into bytes
2346unless the library has been told to transform it into another format.
2347For example, 4 bit/pixel paletted or grayscale data will be returned
23482 pixels/byte with the leftmost pixel in the high-order bits of the
2349byte, unless png_set_packing() is called. 8-bit RGB data will be stored
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2350in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
2351is called to insert filler bytes, either before or after each RGB triplet.
235216-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
2353byte of the color value first, unless png_set_strip_16() is called to
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]2354transform it to regular RGB RGB triplets, or png_set_filler() or
2355png_set_add alpha() is called to insert filler bytes, either before or
2356after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
2357be modified with
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2358png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2359
2360The following code transforms grayscale images of less than 8 to 8 bits,
2361changes paletted images to RGB, and adds a full alpha channel if there is
2362transparency information in a tRNS chunk. This is most useful on
2363grayscale images with bit depths of 2 or 4 or if there is a multiple-image
2364viewing application that wishes to treat all images in the same way.
2365
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2366 if (color_type == PNG_COLOR_TYPE_PALETTE)
2367 png_set_palette_to_rgb(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2368
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2369 if (png_get_valid(png_ptr, info_ptr,
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2370 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
2371
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2372 if (color_type == PNG_COLOR_TYPE_GRAY &&
2373 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
2374
2375The first two functions are actually aliases for png_set_expand(), added
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2376in libpng version 1.0.4, with the function names expanded to improve code
2377readability. In some future version they may actually do different
2378things.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2379
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]2380As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
2381added. It expands the sample depth without changing tRNS to alpha.
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]2382
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2383As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2384png_set_expand(), however, the resultant channels have 16 bits rather than 8.
2385Use this when the output color or gray channels are made linear to avoid fairly
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2386severe accuracy loss.
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]2387
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2388 if (bit_depth < 16)
2389 png_set_expand_16(png_ptr);
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]2390
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2391PNG can have files with 16 bits per channel. If you only can handle
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]23928 bits per channel, this will strip the pixels down to 8-bit.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2393
2394 if (bit_depth == 16)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2395 png_set_strip_16(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2396
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2397If you need to process the alpha channel on the image separately from the image
2398data (for example if you convert it to a bitmap mask) it is possible to have
2399libpng strip the channel leaving just RGB or gray data:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2400
2401 if (color_type & PNG_COLOR_MASK_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2402 png_set_strip_alpha(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2403
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2404If you strip the alpha channel you need to find some other way of dealing with
2405the information. If, instead, you want to convert the image to an opaque
2406version with no alpha channel use png_set_background; see below.
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2407
2408As of libpng version 1.5.2, almost all useful expansions are supported, the
Glenn Randers-Pehrsoncd116fa2011-05-17 06:56:50 -0500[diff] [blame]2409major ommissions are conversion of grayscale to indexed images (which can be
2410done trivially in the application) and conversion of indexed to grayscale (which
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2411can be done by a trivial manipulation of the palette.)
2412
2413In the following table, the 01 means grayscale with depth<8, 31 means
2414indexed with depth<8, other numerals represent the color type, "T" means
2415the tRNS chunk is present, A means an alpha channel is present, and O
2416means tRNS or alpha is present but all pixels in the image are opaque.
2417
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2418 FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2419 TO
2420 01 - [G] - - - - - - - - - - - - -
2421 31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q
2422 0 1 G + . . G G G G G G B B GB GB
2423 0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt
2424 0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt
2425 2 C P C C C + . . C - - CB CB B B
2426 2T Ct - Ct C C t + t - - - CBt CBt Bt Bt
2427 2O Ct - Ct C C t t + - - - CBt CBt Bt Bt
2428 3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q
2429 3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt
2430 3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt
2431 4A lA G A T T GA GT GT GA GT GT + BA G GBA
2432 4O lA GBA A T T GA GT GT GA GT GT BA + GBA G
2433 6A CA PA CA C C A T tT PA P P C CBA + BA
2434 6O CA PBA CA C C A tT T PA P P CBA C BA +
2435
2436Within the matrix,
2437 "+" identifies entries where 'from' and 'to' are the same.
2438 "-" means the transformation is not supported.
2439 "." means nothing is necessary (a tRNS chunk can just be ignored).
2440 "t" means the transformation is obtained by png_set_tRNS.
2441 "A" means the transformation is obtained by png_set_add_alpha().
2442 "X" means the transformation is obtained by png_set_expand().
2443 "1" means the transformation is obtained by
2444 png_set_expand_gray_1_2_4_to_8() (and by png_set_expand() if there
2445 is no transparency in the original or the final format).
2446 "C" means the transformation is obtained by png_set_gray_to_rgb().
Glenn Randers-Pehrsonc36074e2011-05-16 09:08:51 -0500[diff] [blame]2447 "G" means the transformation is obtained by png_set_rgb_to_gray().
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2448 "P" means the transformation is obtained by
2449 png_set_expand_palette_to_rgb().
2450 "p" means the transformation is obtained by png_set_packing().
2451 "Q" means the transformation is obtained by png_set_quantize().
2452 "T" means the transformation is obtained by png_set_tRNS_to_alpha().
2453 "B" means the transformation is obtained by png_set_background(), or
2454 png_strip_alpha().
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2455
2456When an entry has multiple transforms listed all are required to cause the
2457right overall transformation. When two transforms are separated by a comma
2458either will do the job. When transforms are enclosed in [] the transform should
2459do the job but this is currently unimplemented - a different format will result
2460if the suggested transformations are used.
2461
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2462In PNG files, the alpha channel in an image
2463is the level of opacity. If you need the alpha channel in an image to
2464be the level of transparency instead of opacity, you can invert the
2465alpha channel (or the tRNS chunk data) after it's read, so that 0 is
2466fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
2467images) is fully transparent, with
2468
2469 png_set_invert_alpha(png_ptr);
2470
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2471PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2472they can, resulting in, for example, 8 pixels per byte for 1 bit
2473files. This code expands to 1 pixel per byte without changing the
2474values of the pixels:
2475
2476 if (bit_depth < 8)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2477 png_set_packing(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2478
2479PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
2480stored in a PNG image have been "scaled" or "shifted" up to the next
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]2481higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
2482to 8 bits/sample in the range [0, 255]). However, it is also possible
2483to convert the PNG pixel data back to the original bit depth of the
2484image. This call reduces the pixels back down to the original bit depth:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2485
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]2486 png_color_8p sig_bit;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2487
2488 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2489 png_set_shift(png_ptr, sig_bit);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2490
2491PNG files store 3-color pixels in red, green, blue order. This code
2492changes the storage of the pixels to blue, green, red:
2493
2494 if (color_type == PNG_COLOR_TYPE_RGB ||
2495 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2496 png_set_bgr(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2497
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]2498PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
2499into 4 or 8 bytes for windowing systems that need them in this format:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2500
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]2501 if (color_type == PNG_COLOR_TYPE_RGB)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2502 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2503
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2504where "filler" is the 8 or 16-bit number to fill with, and the location is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2505either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
2506you want the filler before the RGB or after. This transformation
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]2507does not affect images that already have full alpha channels. To add an
2508opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
2509will generate RGBA pixels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2510
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2511Note that png_set_filler() does not change the color type. If you want
2512to do that, you can add a true alpha channel with
2513
2514 if (color_type == PNG_COLOR_TYPE_RGB ||
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2515 color_type == PNG_COLOR_TYPE_GRAY)
2516 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2517
2518where "filler" contains the alpha value to assign to each pixel.
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]2519This function was added in libpng-1.2.7.
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2520
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2521If you are reading an image with an alpha channel, and you need the
2522data as ARGB instead of the normal PNG format RGBA:
2523
2524 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2525 png_set_swap_alpha(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2526
2527For some uses, you may want a grayscale image to be represented as
2528RGB. This code will do that conversion:
2529
2530 if (color_type == PNG_COLOR_TYPE_GRAY ||
2531 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2532 png_set_gray_to_rgb(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2533
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2534Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2535with alpha.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2536
2537 if (color_type == PNG_COLOR_TYPE_RGB ||
2538 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2539 png_set_rgb_to_gray(png_ptr, error_action, double red_weight,
2540 double green_weight);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2541
2542 error_action = 1: silently do the conversion
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2543
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2544 error_action = 2: issue a warning if the original
2545 image has any pixel where
2546 red != green or red != blue
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2547
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2548 error_action = 3: issue an error and abort the
2549 conversion if the original
2550 image has any pixel where
2551 red != green or red != blue
2552
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2553 red_weight: weight of red component
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2554
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2555 green_weight: weight of green component
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2556 If either weight is negative, default
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2557 weights are used.
2558
2559In the corresponding fixed point API the red_weight and green_weight values are
2560simply scaled by 100,000:
2561
2562 png_set_rgb_to_gray(png_ptr, error_action, png_fixed_point red_weight,
2563 png_fixed_point green_weight);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2564
2565If you have set error_action = 1 or 2, you can
2566later check whether the image really was gray, after processing
2567the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
2568It will return a png_byte that is zero if the image was gray or
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]25691 if there were any non-gray pixels. Background and sBIT data
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2570will be silently converted to grayscale, using the green channel
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2571data for sBIT, regardless of the error_action setting.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2572
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2573The default values come from the PNG file cHRM chunk if present, otherwise the
2574defaults correspond to the ITU-R recommendation 709, and also the sRGB color
2575space, as recommended in the Charles Poynton's Colour FAQ,
2576<http://www.poynton.com/>, in section 9:
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2577
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2578 <http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2579
2580 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
2581
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2582The calculation is done in a linear colorspace, if the image gamma
Glenn Randers-Pehrson9962b842011-01-24 00:12:14 -0600[diff] [blame]2583can be determined.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2584
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2585The png_set_background() function has been described already, it tells libpng to
2586composite images with alpha or simple transparency against the supplied
2587background color. For compatibility with versions of libpng earlier than
2588libpng-1.5.3 it is recommended that you call the function after reading the file
2589header, even if you don't want to use the color in a bKGD chunk, if one exists.
2590
2591If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
2592you may use this color, or supply another color more suitable for
2593the current display (e.g., the background color from a web page). You
2594need to tell libpng how the color is represented, both the format of the
2595component values in the color (the number of bits) and the gamme encoding of the
2596color. The function takes two arguments, background_gamma_mode and need_expand
2597to convey this information, however only two combinations are like to be useful:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2598
2599 png_color_16 my_background;
2600 png_color_16p image_background;
2601
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]2602 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2603 png_set_background(png_ptr, image_background,
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2604 PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2605 else
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2606 png_set_background(png_ptr, &my_background,
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2607 PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2608
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2609
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2610The second call was described above - my_background is in the format of the
2611final, display, output produced by libpng. Because you now know the format of
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]2612the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
2613output and to retain palette images (the palette colors will be modified
2614appropriately and the tRNS chunk removed.) However, if you are doing this,
2615take great care not to ask for transformations without checking first that
2616they apply!
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2617
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2618In the first call the background color has the original bit depth and color type
2619of the PNG file. So, for palette images the color is supplied as a palette
2620index and for low bit greyscale images the color is a reduced bit value in
2621image_background->gray.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2622
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2623If you didn't call png_set_gamma() before reading the file header, for example
2624if you need your code to remain compatible with older versions of libpng prior
2625to libpng-1.5.3, this is the place to call it.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2626
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2627Do not call it if you called png_set_alpha_mode(); doing so will damage the
2628settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
2629supported then you can certainly do png_set_gamma() before reading the PNG
2630header.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2631
Glenn Randers-Pehrsonc7822512011-05-07 21:23:43 -0500[diff] [blame]2632This API unconditionally sets the screen and file gamma values, so it will
2633override the value in the PNG file unless it is called before the PNG file
2634reading starts. For this reason you must always call it with the PNG file
2635value when you call it in this position:
2636
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]2637 if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
2638 png_set_gamma(png_ptr, screen_gamma, file_gamma);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2639
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2640 else
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2641 png_set_gamma(png_ptr, screen_gamma, 0.45455);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2642
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2643If you need to reduce an RGB file to a paletted file, or if a paletted
2644file has more entries then will fit on your screen, png_set_quantize()
Glenn Randers-Pehrson862cb202010-04-16 22:12:51 -0500[diff] [blame]2645will do that. Note that this is a simple match quantization that merely
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2646finds the closest color available. This should work fairly well with
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2647optimized palettes, but fairly badly with linear color cubes. If you
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2648pass a palette that is larger then maximum_colors, the file will
2649reduce the number of colors in the palette so it will fit into
2650maximum_colors. If there is a histogram, it will use it to make
2651more intelligent choices when reducing the palette. If there is no
2652histogram, it may not do as good a job.
2653
2654 if (color_type & PNG_COLOR_MASK_COLOR)
2655 {
2656 if (png_get_valid(png_ptr, info_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2657 PNG_INFO_PLTE))
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2658 {
2659 png_uint_16p histogram = NULL;
2660
2661 png_get_hIST(png_ptr, info_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2662 &histogram);
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2663 png_set_quantize(png_ptr, palette, num_palette,
2664 max_screen_colors, histogram, 1);
2665 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2666
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2667 else
2668 {
2669 png_color std_color_cube[MAX_SCREEN_COLORS] =
2670 { ... colors ... };
2671
2672 png_set_quantize(png_ptr, std_color_cube,
2673 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
2674 NULL,0);
2675 }
2676 }
2677
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2678PNG files describe monochrome as black being zero and white being one.
2679The following code will reverse this (make black be one and white be
2680zero):
2681
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]2682 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
2683 png_set_invert_mono(png_ptr);
2684
2685This function can also be used to invert grayscale and gray-alpha images:
2686
2687 if (color_type == PNG_COLOR_TYPE_GRAY ||
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2688 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2689 png_set_invert_mono(png_ptr);
2690
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]2691PNG files store 16-bit pixels in network byte order (big-endian,
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2692ie. most significant bits first). This code changes the storage to the
2693other way (little-endian, i.e. least significant bits first, the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2694way PCs store them):
2695
2696 if (bit_depth == 16)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2697 png_set_swap(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2698
2699If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2700need to change the order the pixels are packed into bytes, you can use:
2701
2702 if (bit_depth < 8)
2703 png_set_packswap(png_ptr);
2704
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2705Finally, you can write your own transformation function if none of
2706the existing ones meets your needs. This is done by setting a callback
2707with
2708
2709 png_set_read_user_transform_fn(png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2710 read_transform_fn);
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2711
2712You must supply the function
2713
Glenn Randers-Pehrson93215672011-02-13 19:42:19 -0600[diff] [blame]2714 void read_transform_fn(png_structp png_ptr, png_row_infop
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2715 row_info, png_bytep data)
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2716
2717See pngtest.c for a working example. Your function will be called
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]2718after all of the other transformations have been processed. Take care with
2719interlaced images if you do the interlace yourself - the width of the row is the
2720width in 'row_info', not the overall image width.
2721
2722If supported libpng provides two information routines that you can use to find
2723where you are in processing the image:
2724
2725 png_get_current_pass_number(png_structp png_ptr);
2726 png_get_current_row_number(png_structp png_ptr);
2727
2728Don't try using these outside a transform callback - firstly they are only
2729supported if user transforms are supported, secondly they may well return
2730unexpected results unless the row is actually being processed at the moment they
2731are called.
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2732
John Bowlercd113452011-02-16 06:15:13 -0600[diff] [blame]2733With interlaced
2734images the value returned is the row in the input sub-image image. Use
2735PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
2736find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
2737
2738The discussion of interlace handling above contains more information on how to
2739use these values.
2740
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2741You can also set up a pointer to a user structure for use by your
2742callback function, and you can inform libpng that your transform
2743function will change the number of channels or bit depth with the
2744function
2745
2746 png_set_user_transform_info(png_ptr, user_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2747 user_depth, user_channels);
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2748
2749The user's application, not libpng, is responsible for allocating and
2750freeing any memory required for the user structure.
2751
2752You can retrieve the pointer via the function
2753png_get_user_transform_ptr(). For example:
2754
2755 voidp read_user_transform_ptr =
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2756 png_get_user_transform_ptr(png_ptr);
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2757
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2758The last thing to handle is interlacing; this is covered in detail below,
2759but you must call the function here if you want libpng to handle expansion
2760of the interlaced image.
2761
2762 number_of_passes = png_set_interlace_handling(png_ptr);
2763
2764After setting the transformations, libpng can update your png_info
2765structure to reflect any transformations you've requested with this
2766call. This is most useful to update the info structure's rowbytes
2767field so you can use it to allocate your image memory. This function
2768will also update your palette with the correct screen_gamma and
2769background if these have been given with the calls above.
2770
2771 png_read_update_info(png_ptr, info_ptr);
2772
2773After you call png_read_update_info(), you can allocate any
2774memory you need to hold the image. The row data is simply
2775raw byte data for all forms of images. As the actual allocation
2776varies among applications, no example will be given. If you
2777are allocating one large chunk, you will need to build an
2778array of pointers to each row, as it will be needed for some
2779of the functions below.
2780
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2781Remember: Before you call png_read_update_info(), the png_get_
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]2782functions return the values corresponding to the original PNG image.
2783After you call png_read_update_info the values refer to the image
2784that libpng will output. Consequently you must call all the png_set_
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2785functions before you call png_read_update_info(). This is particularly
2786important for png_set_interlace_handling() - if you are going to call
2787png_read_update_info() you must call png_set_interlace_handling() before
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]2788it unless you want to receive interlaced output.
2789
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2790.SS Reading image data
2791
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2792After you've allocated memory, you can read the image data.
2793The simplest way to do this is in one function call. If you are
2794allocating enough memory to hold the whole image, you can just
2795call png_read_image() and libpng will read in all the image data
2796and put it in the memory area supplied. You will need to pass in
2797an array of pointers to each row.
2798
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]2799This function automatically handles interlacing, so you don't
2800need to call png_set_interlace_handling() (unless you call
2801png_read_update_info()) or call this function multiple times, or any
2802of that other stuff necessary with png_read_rows().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2803
2804 png_read_image(png_ptr, row_pointers);
2805
2806where row_pointers is:
2807
2808 png_bytep row_pointers[height];
2809
2810You can point to void or char or whatever you use for pixels.
2811
2812If you don't want to read in the whole image at once, you can
2813use png_read_rows() instead. If there is no interlacing (check
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2814interlace_type == PNG_INTERLACE_NONE), this is simple:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2815
2816 png_read_rows(png_ptr, row_pointers, NULL,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2817 number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2818
2819where row_pointers is the same as in the png_read_image() call.
2820
2821If you are doing this just one row at a time, you can do this with
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2822a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2823
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2824 png_bytep row_pointer = row;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2825 png_read_row(png_ptr, row_pointer, NULL);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2826
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2827If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
2828get somewhat harder. The only current (PNG Specification version 1.2)
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2829interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
2830a somewhat complicated 2D interlace scheme, known as Adam7, that
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2831breaks down an image into seven smaller images of varying size, based
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2832on an 8x8 grid. This number is defined (from libpng 1.5) as
2833PNG_INTERLACE_ADAM7_PASSES in png.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2834
2835libpng can fill out those images or it can give them to you "as is".
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2836It is almost always better to have libpng handle the interlacing for you.
2837If you want the images filled out, there are two ways to do that. The one
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2838mentioned in the PNG specification is to expand each pixel to cover
2839those pixels that have not been read yet (the "rectangle" method).
2840This results in a blocky image for the first pass, which gradually
2841smooths out as more pixels are read. The other method is the "sparkle"
2842method, where pixels are drawn only in their final locations, with the
2843rest of the image remaining whatever colors they were initialized to
2844before the start of the read. The first method usually looks better,
2845but tends to be slower, as there are more pixels to put in the rows.
2846
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2847If, as is likely, you want libpng to expand the images, call this before
2848calling png_start_read_image() or png_read_update_info():
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2849
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2850 if (interlace_type == PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2851 number_of_passes
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2852 = png_set_interlace_handling(png_ptr);
2853
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2854This will return the number of passes needed. Currently, this is seven,
2855but may change if another interlace type is added. This function can be
2856called even if the file is not interlaced, where it will return one pass.
2857You then need to read the whole image 'number_of_passes' times. Each time
2858will distribute the pixels from the current pass to the correct place in
2859the output image, so you need to supply the same rows to png_read_rows in
2860each pass.
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]2861
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2862If you are not going to display the image after each pass, but are
2863going to wait until the entire image is read in, use the sparkle
2864effect. This effect is faster and the end result of either method
2865is exactly the same. If you are planning on displaying the image
2866after each pass, the "rectangle" effect is generally considered the
2867better looking one.
2868
2869If you only want the "sparkle" effect, just call png_read_rows() as
2870normal, with the third parameter NULL. Make sure you make pass over
2871the image number_of_passes times, and you don't change the data in the
2872rows between calls. You can change the locations of the data, just
2873not the data. Each pass only writes the pixels appropriate for that
2874pass, and assumes the data from previous passes is still valid.
2875
2876 png_read_rows(png_ptr, row_pointers, NULL,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2877 number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2878
2879If you only want the first effect (the rectangles), do the same as
2880before except pass the row buffer in the third parameter, and leave
2881the second parameter NULL.
2882
2883 png_read_rows(png_ptr, NULL, row_pointers,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2884 number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2885
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2886If you don't want libpng to handle the interlacing details, just call
2887png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
2888Each of the images is a valid image by itself, however you will almost
2889certainly need to distribute the pixels from each sub-image to the
2890correct place. This is where everything gets very tricky.
2891
2892If you want to retrieve the separate images you must pass the correct
2893number of rows to each successive call of png_read_rows(). The calculation
2894gets pretty complicated for small images, where some sub-images may
2895not even exist because either their width or height ends up zero.
2896libpng provides two macros to help you in 1.5 and later versions:
2897
2898 png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
2899 png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
2900
2901Respectively these tell you the width and height of the sub-image
2902corresponding to the numbered pass. 'pass' is in in the range 0 to 6 -
2903this can be confusing because the specification refers to the same passes
2904as 1 to 7! Be careful, you must check both the width and height before
2905calling png_read_rows() and not call it for that pass if either is zero.
2906
2907You can, of course, read each sub-image row by row. If you want to
2908produce optimal code to make a pixel-by-pixel transformation of an
2909interlaced image this is the best approach; read each row of each pass,
2910transform it, and write it out to a new interlaced image.
2911
2912If you want to de-interlace the image yourself libpng provides further
2913macros to help that tell you where to place the pixels in the output image.
2914Because the interlacing scheme is rectangular - sub-image pixels are always
2915arranged on a rectangular grid - all you need to know for each pass is the
2916starting column and row in the output image of the first pixel plus the
2917spacing between each pixel. As of libpng 1.5 there are four macros to
2918retrieve this information:
2919
2920 png_uint_32 x = PNG_PASS_START_COL(pass);
2921 png_uint_32 y = PNG_PASS_START_ROW(pass);
2922 png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass);
2923 png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass);
2924
2925These allow you to write the obvious loop:
2926
2927 png_uint_32 input_y = 0;
2928 png_uint_32 output_y = PNG_PASS_START_ROW(pass);
2929
2930 while (output_y < output_image_height)
2931 {
2932 png_uint_32 input_x = 0;
2933 png_uint_32 output_x = PNG_PASS_START_COL(pass);
2934
2935 while (output_x < output_image_width)
2936 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2937 image[output_y][output_x] =
2938 subimage[pass][input_y][input_x++];
2939
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2940 output_x += xStep;
2941 }
2942
2943 ++input_y;
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2944 output_y += yStep;
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2945 }
2946
2947Notice that the steps between successive output rows and columns are
2948returned as shifts. This is possible because the pixels in the subimages
2949are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original
2950image. In practice you may need to directly calculate the output coordinate
2951given an input coordinate. libpng provides two further macros for this
2952purpose:
2953
2954 png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass);
2955 png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass);
2956
2957Finally a pair of macros are provided to tell you if a particular image
2958row or column appears in a given pass:
2959
2960 int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass);
2961 int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass);
2962
2963Bear in mind that you will probably also need to check the width and height
2964of the pass in addition to the above to be sure the pass even exists!
2965
2966With any luck you are convinced by now that you don't want to do your own
2967interlace handling. In reality normally the only good reason for doing this
2968is if you are processing PNG files on a pixel-by-pixel basis and don't want
2969to load the whole file into memory when it is interlaced.
2970
2971libpng includes a test program, pngvalid, that illustrates reading and
2972writing of interlaced images. If you can't get interlacing to work in your
2973code and don't want to leave it to libpng (the recommended approach) see
2974how pngvalid.c does it.
2975
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2976.SS Finishing a sequential read
2977
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]2978After you are finished reading the image through the
2979low-level interface, you can finish reading the file. If you are
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2980interested in comments or time, which may be stored either before or
2981after the image data, you should pass the separate png_info struct if
2982you want to keep the comments from before and after the image
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]2983separate.
2984
2985 png_infop end_info = png_create_info_struct(png_ptr);
2986
2987 if (!end_info)
2988 {
2989 png_destroy_read_struct(&png_ptr, &info_ptr,
2990 (png_infopp)NULL);
2991 return (ERROR);
2992 }
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2993
2994 png_read_end(png_ptr, end_info);
2995
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]2996If you are not interested, you should still call png_read_end()
2997but you can pass NULL, avoiding the need to create an end_info structure.
2998
2999 png_read_end(png_ptr, (png_infop)NULL);
3000
Glenn Randers-Pehrson99778e12011-04-20 17:43:52 -0500[diff] [blame]3001If you don't call png_read_end(), then your file pointer will be
3002left pointing to the first chunk after the last IDAT, which is probably
3003not what you want if you expect to read something beyond the end of
3004the PNG datastream.
3005
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3006When you are done, you can free all memory allocated by libpng like this:
3007
3008 png_destroy_read_struct(&png_ptr, &info_ptr,
3009 &end_info);
3010
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]3011or, if you didn't create an end_info structure,
3012
3013 png_destroy_read_struct(&png_ptr, &info_ptr,
3014 (png_infopp)NULL);
3015
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3016It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3017point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3018
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3019 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3020
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3021 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3022 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3023 more of
3024 PNG_FREE_PLTE, PNG_FREE_TRNS,
3025 PNG_FREE_HIST, PNG_FREE_ICCP,
3026 PNG_FREE_PCAL, PNG_FREE_ROWS,
3027 PNG_FREE_SCAL, PNG_FREE_SPLT,
3028 PNG_FREE_TEXT, PNG_FREE_UNKN,
3029 or simply PNG_FREE_ALL
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3030
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3031 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3032 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3033
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3034This function may be safely called when the relevant storage has
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]3035already been freed, or has not yet been allocated, or was allocated
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3036by the user and not by libpng, and will in those cases do nothing.
3037The "seq" parameter is ignored if only one item of the selected data
3038type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
3039are allowed for the data type identified in the mask, such as text or
3040sPLT, only the n'th item in the structure is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3041
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3042The default behavior is only to free data that was allocated internally
3043by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3044or so that it will free data that was allocated by the user with png_malloc()
3045or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3046
3047 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3048
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3049 freer - one of
3050 PNG_DESTROY_WILL_FREE_DATA
3051 PNG_SET_WILL_FREE_DATA
3052 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3053
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3054 mask - which data elements are affected
3055 same choices as in png_free_data()
3056
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3057This function only affects data that has already been allocated.
3058You can call this function after reading the PNG data but before calling
3059any png_set_*() functions, to control whether the user or the png_set_*()
3060function is responsible for freeing any existing data that might be present,
3061and again after the png_set_*() functions to control whether the user
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3062or png_destroy_*() is supposed to free the data. When the user assumes
3063responsibility for libpng-allocated data, the application must use
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3064png_free() to free it, and when the user transfers responsibility to libpng
3065for data that the user has allocated, the user must have used png_malloc()
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]3066or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3067
3068If you allocated your row_pointers in a single block, as suggested above in
3069the description of the high level read interface, you must not transfer
3070responsibility for freeing it to the png_set_rows or png_read_destroy function,
3071because they would also try to free the individual row_pointers[i].
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3072
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3073If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
3074separately, do not transfer responsibility for freeing text_ptr to libpng,
3075because when libpng fills a png_text structure it combines these members with
3076the key member, and png_free_data() will free only text_ptr.key. Similarly,
3077if you transfer responsibility for free'ing text_ptr from libpng to your
3078application, your application must not separately free those members.
3079
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3080The png_free_data() function will turn off the "valid" flag for anything
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3081it frees. If you need to turn the flag off for a chunk that was freed by
3082your application instead of by libpng, you can use
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3083
3084 png_set_invalid(png_ptr, info_ptr, mask);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3085
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3086 mask - identifies the chunks to be made invalid,
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3087 containing the bitwise OR of one or
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]3088 more of
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3089 PNG_INFO_gAMA, PNG_INFO_sBIT,
3090 PNG_INFO_cHRM, PNG_INFO_PLTE,
3091 PNG_INFO_tRNS, PNG_INFO_bKGD,
3092 PNG_INFO_hIST, PNG_INFO_pHYs,
3093 PNG_INFO_oFFs, PNG_INFO_tIME,
3094 PNG_INFO_pCAL, PNG_INFO_sRGB,
3095 PNG_INFO_iCCP, PNG_INFO_sPLT,
3096 PNG_INFO_sCAL, PNG_INFO_IDAT
3097
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3098For a more compact example of reading a PNG image, see the file example.c.
3099
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3100.SS Reading PNG files progressively
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3101
3102The progressive reader is slightly different then the non-progressive
3103reader. Instead of calling png_read_info(), png_read_rows(), and
3104png_read_end(), you make one call to png_process_data(), which calls
3105callbacks when it has the info, a row, or the end of the image. You
3106set up these callbacks with png_set_progressive_read_fn(). You don't
3107have to worry about the input/output functions of libpng, as you are
3108giving the library the data directly in png_process_data(). I will
3109assume that you have read the section on reading PNG files above,
3110so I will only highlight the differences (although I will show
3111all of the code).
3112
3113png_structp png_ptr;
3114png_infop info_ptr;
3115
3116 /* An example code fragment of how you would
3117 initialize the progressive reader in your
3118 application. */
3119 int
3120 initialize_png_reader()
3121 {
3122 png_ptr = png_create_read_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3123 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3124 user_error_fn, user_warning_fn);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3125
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3126 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]3127 return (ERROR);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3128
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3129 info_ptr = png_create_info_struct(png_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3130
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3131 if (!info_ptr)
3132 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3133 png_destroy_read_struct(&png_ptr,
3134 (png_infopp)NULL, (png_infopp)NULL);
3135 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3136 }
3137
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3138 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3139 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3140 png_destroy_read_struct(&png_ptr, &info_ptr,
3141 (png_infopp)NULL);
3142 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3143 }
3144
3145 /* This one's new. You can provide functions
3146 to be called when the header info is valid,
3147 when each row is completed, and when the image
3148 is finished. If you aren't using all functions,
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3149 you can specify NULL parameters. Even when all
3150 three functions are NULL, you need to call
3151 png_set_progressive_read_fn(). You can use
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3152 any struct as the user_ptr (cast to a void pointer
3153 for the function call), and retrieve the pointer
3154 from inside the callbacks using the function
3155
3156 png_get_progressive_ptr(png_ptr);
3157
3158 which will return a void pointer, which you have
3159 to cast appropriately.
3160 */
3161 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
3162 info_callback, row_callback, end_callback);
3163
3164 return 0;
3165 }
3166
3167 /* A code fragment that you call as you receive blocks
3168 of data */
3169 int
3170 process_data(png_bytep buffer, png_uint_32 length)
3171 {
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3172 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3173 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3174 png_destroy_read_struct(&png_ptr, &info_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3175 (png_infopp)NULL);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3176 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3177 }
3178
3179 /* This one's new also. Simply give it a chunk
3180 of data from the file stream (in order, of
3181 course). On machines with segmented memory
3182 models machines, don't give it any more than
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3183 64K. The library seems to run fine with sizes
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3184 of 4K. Although you can give it much less if
3185 necessary (I assume you can give it chunks of
3186 1 byte, I haven't tried less then 256 bytes
3187 yet). When this function returns, you may
3188 want to display any rows that were generated
3189 in the row callback if you don't already do
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3190 so there.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3191 */
3192 png_process_data(png_ptr, info_ptr, buffer, length);
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]3193
3194 /* At this point you can call png_process_data_skip if
3195 you want to handle data the library will skip yourself;
3196 it simply returns the number of bytes to skip (and stops
3197 libpng skipping that number of bytes on the next
3198 png_process_data call).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3199 return 0;
3200 }
3201
3202 /* This function is called (as set by
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3203 png_set_progressive_read_fn() above) when enough data
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3204 has been supplied so all of the header has been
3205 read.
3206 */
3207 void
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3208 info_callback(png_structp png_ptr, png_infop info)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3209 {
3210 /* Do any setup here, including setting any of
3211 the transformations mentioned in the Reading
3212 PNG files section. For now, you _must_ call
3213 either png_start_read_image() or
3214 png_read_update_info() after all the
3215 transformations are set (even if you don't set
3216 any). You may start getting rows before
3217 png_process_data() returns, so this is your
3218 last chance to prepare for that.
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3219
3220 This is where you turn on interlace handling,
3221 assuming you don't want to do it yourself.
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]3222
3223 If you need to you can stop the processing of
3224 your original input data at this point by calling
3225 png_process_data_pause. This returns the number
3226 of unprocessed bytes from the last png_process_data
3227 call - it is up to you to ensure that the next call
3228 sees these bytes again. If you don't want to bother
3229 with this you can get libpng to cache the unread
3230 bytes by setting the 'save' parameter (see png.h) but
3231 then libpng will have to copy the data internally.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3232 */
3233 }
3234
3235 /* This function is called when each row of image
3236 data is complete */
3237 void
3238 row_callback(png_structp png_ptr, png_bytep new_row,
Glenn Randers-Pehrsone68f5a32001-05-14 09:20:53 -0500[diff] [blame]3239 png_uint_32 row_num, int pass)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3240 {
3241 /* If the image is interlaced, and you turned
3242 on the interlace handler, this function will
3243 be called for every row in every pass. Some
3244 of these rows will not be changed from the
3245 previous pass. When the row is not changed,
3246 the new_row variable will be NULL. The rows
3247 and passes are called in order, so you don't
3248 really need the row_num and pass, but I'm
3249 supplying them because it may make your life
3250 easier.
3251
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3252 If you did not turn on interlace handling then
3253 the callback is called for each row of each
3254 sub-image when the image is interlaced. In this
3255 case 'row_num' is the row in the sub-image, not
3256 the row in the output image as it is in all other
3257 cases.
3258
3259 For the non-NULL rows of interlaced images when
3260 you have switched on libpng interlace handling,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3261 you must call png_progressive_combine_row()
3262 passing in the row and the old row. You can
3263 call this function for NULL rows (it will just
3264 return) and for non-interlaced images (it just
3265 does the memcpy for you) if it will make the
3266 code easier. Thus, you can just do this for
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3267 all cases if you switch on interlace handling;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3268 */
3269
3270 png_progressive_combine_row(png_ptr, old_row,
3271 new_row);
3272
3273 /* where old_row is what was displayed for
Glenn Randers-Pehrson345bc271998-06-14 14:43:31 -0500[diff] [blame]3274 previously for the row. Note that the first
3275 pass (pass == 0, really) will completely cover
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3276 the old row, so the rows do not have to be
3277 initialized. After the first pass (and only
3278 for interlaced images), you will have to pass
3279 the current row, and the function will combine
3280 the old row and the new row.
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]3281
3282 You can also call png_process_data_pause in this
3283 callback - see above.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3284 */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3285 }
3286
3287 void
3288 end_callback(png_structp png_ptr, png_infop info)
3289 {
3290 /* This function is called after the whole image
3291 has been read, including any chunks after the
3292 image (up to and including the IEND). You
3293 will usually have the same info chunk as you
3294 had in the header, although some data may have
3295 been added to the comments and time fields.
3296
3297 Most people won't do much here, perhaps setting
3298 a flag that marks the image as finished.
3299 */
3300 }
3301
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3302
3303
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3304.SH IV. Writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3305
3306Much of this is very similar to reading. However, everything of
3307importance is repeated here, so you won't have to constantly look
3308back up in the reading section to understand writing.
3309
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3310.SS Setup
3311
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3312You will want to do the I/O initialization before you get into libpng,
3313so if it doesn't work, you don't have anything to undo. If you are not
3314using the standard I/O functions, you will need to replace them with
3315custom writing functions. See the discussion under Customizing libpng.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3316
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3317 FILE *fp = fopen(file_name, "wb");
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3318
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3319 if (!fp)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]3320 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3321
3322Next, png_struct and png_info need to be allocated and initialized.
3323As these can be both relatively large, you may not want to store these
3324on the stack, unless you have stack space to spare. Of course, you
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3325will want to check if they return NULL. If you are also reading,
3326you won't want to name your read structure and your write structure
3327both "png_ptr"; you can call them anything you like, such as
3328"read_ptr" and "write_ptr". Look at pngtest.c, for example.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3329
3330 png_structp png_ptr = png_create_write_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3331 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3332 user_error_fn, user_warning_fn);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3333
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3334 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]3335 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3336
3337 png_infop info_ptr = png_create_info_struct(png_ptr);
3338 if (!info_ptr)
3339 {
3340 png_destroy_write_struct(&png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3341 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]3342 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3343 }
3344
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]3345If you want to use your own memory allocation routines,
3346define PNG_USER_MEM_SUPPORTED and use
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3347png_create_write_struct_2() instead of png_create_write_struct():
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]3348
3349 png_structp png_ptr = png_create_write_struct_2
3350 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
3351 user_error_fn, user_warning_fn, (png_voidp)
3352 user_mem_ptr, user_malloc_fn, user_free_fn);
3353
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3354After you have these structures, you will need to set up the
3355error handling. When libpng encounters an error, it expects to
3356longjmp() back to your routine. Therefore, you will need to call
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3357setjmp() and pass the png_jmpbuf(png_ptr). If you
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3358write the file from different routines, you will need to update
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3359the png_jmpbuf(png_ptr) every time you enter a new routine that will
3360call a png_*() function. See your documentation of setjmp/longjmp
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3361for your compiler for more information on setjmp/longjmp. See
3362the discussion on libpng error handling in the Customizing Libpng
3363section below for more information on the libpng error handling.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3364
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3365 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3366 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3367 png_destroy_write_struct(&png_ptr, &info_ptr);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]3368 fclose(fp);
3369 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3370 }
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3371 ...
3372 return;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3373
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3374If you would rather avoid the complexity of setjmp/longjmp issues,
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]3375you can compile libpng with PNG_NO_SETJMP, in which case
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3376errors will result in a call to PNG_ABORT() which defaults to abort().
3377
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]3378You can #define PNG_ABORT() to a function that does something
3379more useful than abort(), as long as your function does not
3380return.
3381
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3382Now you need to set up the output code. The default for libpng is to
3383use the C function fwrite(). If you use this, you will need to pass a
3384valid FILE * in the function png_init_io(). Be sure that the file is
3385opened in binary mode. Again, if you wish to handle writing data in
3386another way, see the discussion on libpng I/O handling in the Customizing
3387Libpng section below.
3388
3389 png_init_io(png_ptr, fp);
3390
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]3391If you are embedding your PNG into a datastream such as MNG, and don't
3392want libpng to write the 8-byte signature, or if you have already
3393written the signature in your application, use
3394
3395 png_set_sig_bytes(png_ptr, 8);
3396
3397to inform libpng that it should not write a signature.
3398
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3399.SS Write callbacks
3400
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3401At this point, you can set up a callback function that will be
3402called after each row has been written, which you can use to control
3403a progress meter or the like. It's demonstrated in pngtest.c.
3404You must supply a function
3405
Glenn Randers-Pehrson81ce8892011-01-24 08:04:37 -0600[diff] [blame]3406 void write_row_callback(png_structp png_ptr, png_uint_32 row,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3407 int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3408 {
3409 /* put your code here */
3410 }
3411
3412(You can give it another name that you like instead of "write_row_callback")
3413
3414To inform libpng about your function, use
3415
3416 png_set_write_status_fn(png_ptr, write_row_callback);
3417
John Bowler59010e52011-02-16 06:16:31 -0600[diff] [blame]3418When this function is called the row has already been completely processed and
3419it has also been written out. The 'row' and 'pass' refer to the next row to be
3420handled. For the
3421non-interlaced case the row that was just handled is simply one less than the
3422passed in row number, and pass will always be 0. For the interlaced case the
3423same applies unless the row value is 0, in which case the row just handled was
3424the last one from one of the preceding passes. Because interlacing may skip a
3425pass you cannot be sure that the preceding pass is just 'pass-1', if you really
3426need to know what the last pass is record (row,pass) from the callback and use
3427the last recorded value each time.
3428
3429As with the user transform you can find the output row using the
3430PNG_ROW_FROM_PASS_ROW macro.
3431
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3432You now have the option of modifying how the compression library will
3433run. The following functions are mainly for testing, but may be useful
3434in some cases, like if you need to write PNG files extremely fast and
3435are willing to give up some compression, or if you want to get the
3436maximum possible compression at the expense of slower writing. If you
3437have no special needs in this area, let the library do what it wants by
3438not calling this function at all, as it has been tuned to deliver a good
3439speed/compression ratio. The second parameter to png_set_filter() is
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3440the filter method, for which the only valid values are 0 (as of the
3441July 1999 PNG specification, version 1.2) or 64 (if you are writing
3442a PNG datastream that is to be embedded in a MNG datastream). The third
3443parameter is a flag that indicates which filter type(s) are to be tested
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3444for each scanline. See the PNG specification for details on the specific
3445filter types.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3446
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3447
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3448 /* turn on or off filtering, and/or choose
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3449 specific filters. You can use either a single
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3450 PNG_FILTER_VALUE_NAME or the bitwise OR of one
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3451 or more PNG_FILTER_NAME masks.
3452 */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3453 png_set_filter(png_ptr, 0,
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3454 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
3455 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
3456 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]3457 PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3458 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
3459 PNG_ALL_FILTERS);
3460
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3461If an application wants to start and stop using particular filters during
3462compression, it should start out with all of the filters (to ensure that
3463the previous row of pixels will be stored in case it's needed later),
3464and then add and remove them after the start of compression.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3465
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3466If you are writing a PNG datastream that is to be embedded in a MNG
3467datastream, the second parameter can be either 0 or 64.
3468
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3469The png_set_compression_*() functions interface to the zlib compression
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3470library, and should mostly be ignored unless you really know what you are
3471doing. The only generally useful call is png_set_compression_level()
3472which changes how much time zlib spends on trying to compress the image
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3473data. See the Compression Library (zlib.h and algorithm.txt, distributed
3474with zlib) for details on the compression levels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3475
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]3476 #include zlib.h
3477
Glenn Randers-Pehrsona45f47c2011-04-01 15:31:26 -0500[diff] [blame]3478 /* Set the zlib compression level */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3479 png_set_compression_level(png_ptr,
3480 Z_BEST_COMPRESSION);
3481
Glenn Randers-Pehrsona45f47c2011-04-01 15:31:26 -0500[diff] [blame]3482 /* Set other zlib parameters for compressing IDAT */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3483 png_set_compression_mem_level(png_ptr, 8);
3484 png_set_compression_strategy(png_ptr,
3485 Z_DEFAULT_STRATEGY);
3486 png_set_compression_window_bits(png_ptr, 15);
3487 png_set_compression_method(png_ptr, 8);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3488 png_set_compression_buffer_size(png_ptr, 8192)
3489
Glenn Randers-Pehrsona45f47c2011-04-01 15:31:26 -0500[diff] [blame]3490 /* Set zlib parameters for text compression
3491 * If you don't call these, the parameters
3492 * fall back on those defined for IDAT chunks
3493 */
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]3494 png_set_text_compression_mem_level(png_ptr, 8);
3495 png_set_text_compression_strategy(png_ptr,
3496 Z_DEFAULT_STRATEGY);
3497 png_set_text_compression_window_bits(png_ptr, 15);
3498 png_set_text_compression_method(png_ptr, 8);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3499
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3500.SS Setting the contents of info for output
3501
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3502You now need to fill in the png_info structure with all the data you
3503wish to write before the actual image. Note that the only thing you
3504are allowed to write after the image is the text chunks and the time
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3505chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3506the latest PNG specification for more information on that. If you
3507wish to write them before the image, fill them in now, and flag that
3508data as being valid. If you want to wait until after the data, don't
3509fill them until png_write_end(). For all the fields in png_info and
3510their data types, see png.h. For explanations of what the fields
3511contain, see the PNG specification.
3512
3513Some of the more important parts of the png_info are:
3514
3515 png_set_IHDR(png_ptr, info_ptr, width, height,
3516 bit_depth, color_type, interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3517 compression_type, filter_method)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3518
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3519 width - holds the width of the image
3520 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3521
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3522 height - holds the height of the image
3523 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3524
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3525 bit_depth - holds the bit depth of one of the
3526 image channels.
3527 (valid values are 1, 2, 4, 8, 16
3528 and depend also on the
3529 color_type. See also significant
3530 bits (sBIT) below).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3531
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3532 color_type - describes which color/alpha
3533 channels are present.
3534 PNG_COLOR_TYPE_GRAY
3535 (bit depths 1, 2, 4, 8, 16)
3536 PNG_COLOR_TYPE_GRAY_ALPHA
3537 (bit depths 8, 16)
3538 PNG_COLOR_TYPE_PALETTE
3539 (bit depths 1, 2, 4, 8)
3540 PNG_COLOR_TYPE_RGB
3541 (bit_depths 8, 16)
3542 PNG_COLOR_TYPE_RGB_ALPHA
3543 (bit_depths 8, 16)
3544
3545 PNG_COLOR_MASK_PALETTE
3546 PNG_COLOR_MASK_COLOR
3547 PNG_COLOR_MASK_ALPHA
3548
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3549 interlace_type - PNG_INTERLACE_NONE or
3550 PNG_INTERLACE_ADAM7
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3551
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3552 compression_type - (must be
3553 PNG_COMPRESSION_TYPE_DEFAULT)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3554
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3555 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
3556 or, if you are writing a PNG to
3557 be embedded in a MNG datastream,
3558 can also be
3559 PNG_INTRAPIXEL_DIFFERENCING)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3560
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3561If you call png_set_IHDR(), the call must appear before any of the
Glenn Randers-Pehrsond60c8862009-06-15 21:56:14 -0500[diff] [blame]3562other png_set_*() functions, because they might require access to some of
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3563the IHDR settings. The remaining png_set_*() functions can be called
3564in any order.
3565
Glenn Randers-Pehrsonb5444a12009-06-08 08:36:19 -0500[diff] [blame]3566If you wish, you can reset the compression_type, interlace_type, or
3567filter_method later by calling png_set_IHDR() again; if you do this, the
3568width, height, bit_depth, and color_type must be the same in each call.
Glenn Randers-Pehrson424c9852009-06-02 13:45:15 -0500[diff] [blame]3569
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3570 png_set_PLTE(png_ptr, info_ptr, palette,
3571 num_palette);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3572
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3573 palette - the palette for the file
3574 (array of png_color)
3575 num_palette - number of entries in the palette
3576
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]3577 png_set_gAMA(png_ptr, info_ptr, file_gamma);
3578 png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3579
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]3580 file_gamma - the gamma at which the image was
3581 created (PNG_INFO_gAMA)
3582
3583 int_file_gamma - 100,000 times the gamma at which
3584 the image was created
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3585
3586 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3587
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3588 srgb_intent - the rendering intent
3589 (PNG_INFO_sRGB) The presence of
3590 the sRGB chunk means that the pixel
3591 data is in the sRGB color space.
3592 This chunk also implies specific
3593 values of gAMA and cHRM. Rendering
3594 intent is the CSS-1 property that
3595 has been defined by the International
3596 Color Consortium
3597 (http://www.color.org).
3598 It can be one of
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]3599 PNG_sRGB_INTENT_SATURATION,
3600 PNG_sRGB_INTENT_PERCEPTUAL,
3601 PNG_sRGB_INTENT_ABSOLUTE, or
3602 PNG_sRGB_INTENT_RELATIVE.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3603
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3604
3605 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
3606 srgb_intent);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3607
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3608 srgb_intent - the rendering intent
3609 (PNG_INFO_sRGB) The presence of the
3610 sRGB chunk means that the pixel
3611 data is in the sRGB color space.
3612 This function also causes gAMA and
3613 cHRM chunks with the specific values
3614 that are consistent with sRGB to be
3615 written.
3616
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3617 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3618 profile, proflen);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3619
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3620 name - The profile name.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3621
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3622 compression_type - The compression type; always
3623 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
3624 You may give NULL to this argument to
3625 ignore it.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3626
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3627 profile - International Color Consortium color
3628 profile data. May contain NULs.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3629
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3630 proflen - length of profile data in bytes.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3631
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3632 png_set_sBIT(png_ptr, info_ptr, sig_bit);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3633
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3634 sig_bit - the number of significant bits for
3635 (PNG_INFO_sBIT) each of the gray, red,
3636 green, and blue channels, whichever are
3637 appropriate for the given color type
3638 (png_color_16)
3639
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]3640 png_set_tRNS(png_ptr, info_ptr, trans_alpha,
3641 num_trans, trans_color);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3642
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]3643 trans_alpha - array of alpha (transparency)
3644 entries for palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3645
Glenn Randers-Pehrsonb5444a12009-06-08 08:36:19 -0500[diff] [blame]3646 trans_color - graylevel or color sample values
3647 (in order red, green, blue) of the
3648 single transparent color for
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3649 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3650
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3651 num_trans - number of transparent entries
3652 (PNG_INFO_tRNS)
3653
3654 png_set_hIST(png_ptr, info_ptr, hist);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3655
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3656 hist - histogram of palette (array of
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]3657 png_uint_16) (PNG_INFO_hIST)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3658
3659 png_set_tIME(png_ptr, info_ptr, mod_time);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3660
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3661 mod_time - time image was last modified
3662 (PNG_VALID_tIME)
3663
3664 png_set_bKGD(png_ptr, info_ptr, background);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3665
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3666 background - background color (PNG_VALID_bKGD)
3667
3668 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3669
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3670 text_ptr - array of png_text holding image
3671 comments
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3672
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3673 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3674 on "text" PNG_TEXT_COMPRESSION_NONE
3675 PNG_TEXT_COMPRESSION_zTXt
3676 PNG_ITXT_COMPRESSION_NONE
3677 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3678 text_ptr[i].key - keyword for comment. Must contain
3679 1-79 characters.
3680 text_ptr[i].text - text comments for current
3681 keyword. Can be NULL or empty.
3682 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3683 after decompression, 0 for iTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3684 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3685 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3686 text_ptr[i].lang - language of comment (NULL or
3687 empty for unknown).
3688 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
3689 or empty for unknown).
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]3690 Note that the itxt_length, lang, and lang_key
3691 members of the text_ptr structure only exist
3692 when the library is built with iTXt chunk support.
3693
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3694 num_text - number of comments
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3695
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3696 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
3697 num_spalettes);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3698
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3699 palette_ptr - array of png_sPLT_struct structures
3700 to be added to the list of palettes
3701 in the info structure.
3702 num_spalettes - number of palette structures to be
3703 added.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3704
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3705 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
3706 unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3707
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3708 offset_x - positive offset from the left
3709 edge of the screen
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3710
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3711 offset_y - positive offset from the top
3712 edge of the screen
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3713
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3714 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
3715
3716 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
3717 unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3718
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3719 res_x - pixels/unit physical resolution
3720 in x direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3721
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3722 res_y - pixels/unit physical resolution
3723 in y direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3724
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3725 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3726 PNG_RESOLUTION_METER
3727
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3728 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3729
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3730 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3731
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3732 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3733
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3734 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3735 (width and height are doubles)
3736
3737 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3738
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3739 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3740
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3741 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3742
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3743 height - height of a pixel in physical scale units
3744 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3745
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3746 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
3747 num_unknowns)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3748
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3749 unknowns - array of png_unknown_chunk
3750 structures holding unknown chunks
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3751 unknowns[i].name - name of unknown chunk
3752 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3753 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3754 unknowns[i].location - position to write chunk in file
3755 0: do not write chunk
3756 PNG_HAVE_IHDR: before PLTE
3757 PNG_HAVE_PLTE: before IDAT
3758 PNG_AFTER_IDAT: after IDAT
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3759
3760The "location" member is set automatically according to
3761what part of the output file has already been written.
3762You can change its value after calling png_set_unknown_chunks()
3763as demonstrated in pngtest.c. Within each of the "locations",
3764the chunks are sequenced according to their position in the
3765structure (that is, the value of "i", which is the order in which
3766the chunk was either read from the input file or defined with
3767png_set_unknown_chunks).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3768
3769A quick word about text and num_text. text is an array of png_text
3770structures. num_text is the number of valid structures in the array.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3771Each png_text structure holds a language code, a keyword, a text value,
3772and a compression type.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3773
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3774The compression types have the same valid numbers as the compression
3775types of the image data. Currently, the only valid number is zero.
3776However, you can store text either compressed or uncompressed, unlike
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3777images, which always have to be compressed. So if you don't want the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3778text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3779Because tEXt and zTXt chunks don't have a language field, if you
3780specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
3781any language code or translated keyword will not be written out.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3782
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3783Until text gets around 1000 bytes, it is not worth compressing it.
3784After the text has been written out to the file, the compression type
3785is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
3786so that it isn't written out again at the end (in case you are calling
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3787png_write_end() with the same struct).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3788
3789The keywords that are given in the PNG Specification are:
3790
3791 Title Short (one line) title or
3792 caption for image
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3793
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3794 Author Name of image's creator
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3795
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3796 Description Description of image (possibly long)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3797
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3798 Copyright Copyright notice
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3799
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3800 Creation Time Time of original image creation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3801 (usually RFC 1123 format, see below)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3802
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3803 Software Software used to create the image
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3804
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3805 Disclaimer Legal disclaimer
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3806
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3807 Warning Warning of nature of content
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3808
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3809 Source Device used to create the image
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3810
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3811 Comment Miscellaneous comment; conversion
3812 from other image format
3813
3814The keyword-text pairs work like this. Keywords should be short
3815simple descriptions of what the comment is about. Some typical
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3816keywords are found in the PNG specification, as is some recommendations
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3817on keywords. You can repeat keywords in a file. You can even write
3818some text before the image and some after. For example, you may want
3819to put a description of the image before the image, but leave the
3820disclaimer until after, so viewers working over modem connections
3821don't have to wait for the disclaimer to go over the modem before
3822they start seeing the image. Finally, keywords should be full
3823words, not abbreviations. Keywords and text are in the ISO 8859-1
3824(Latin-1) character set (a superset of regular ASCII) and can not
3825contain NUL characters, and should not contain control or other
3826unprintable characters. To make the comments widely readable, stick
3827with basic ASCII, and avoid machine specific character set extensions
3828like the IBM-PC character set. The keyword must be present, but
3829you can leave off the text string on non-compressed pairs.
3830Compressed pairs must have a text string, as only the text string
3831is compressed anyway, so the compression would be meaningless.
3832
3833PNG supports modification time via the png_time structure. Two
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3834conversion routines are provided, png_convert_from_time_t() for
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3835time_t and png_convert_from_struct_tm() for struct tm. The
3836time_t routine uses gmtime(). You don't have to use either of
3837these, but if you wish to fill in the png_time structure directly,
3838you should provide the time in universal time (GMT) if possible
3839instead of your local time. Note that the year number is the full
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3840year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3841that months start with 1.
3842
3843If you want to store the time of the original image creation, you should
3844use a plain tEXt chunk with the "Creation Time" keyword. This is
3845necessary because the "creation time" of a PNG image is somewhat vague,
3846depending on whether you mean the PNG file, the time the image was
3847created in a non-PNG format, a still photo from which the image was
3848scanned, or possibly the subject matter itself. In order to facilitate
3849machine-readable dates, it is recommended that the "Creation Time"
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3850tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3851although this isn't a requirement. Unlike the tIME chunk, the
3852"Creation Time" tEXt chunk is not expected to be automatically changed
3853by the software. To facilitate the use of RFC 1123 dates, a function
3854png_convert_to_rfc1123(png_timep) is provided to convert from PNG
3855time to an RFC 1123 format string.
3856
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3857.SS Writing unknown chunks
3858
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3859You can use the png_set_unknown_chunks function to queue up chunks
3860for writing. You give it a chunk name, raw data, and a size; that's
3861all there is to it. The chunks will be written by the next following
3862png_write_info_before_PLTE, png_write_info, or png_write_end function.
3863Any chunks previously read into the info structure's unknown-chunk
3864list will also be written out in a sequence that satisfies the PNG
3865specification's ordering rules.
3866
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3867.SS The high-level write interface
3868
3869At this point there are two ways to proceed; through the high-level
3870write interface, or through a sequence of low-level write operations.
3871You can use the high-level interface if your image data is present
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3872in the info structure. All defined output
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3873transformations are permitted, enabled by the following masks.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3874
3875 PNG_TRANSFORM_IDENTITY No transformation
3876 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3877 PNG_TRANSFORM_PACKSWAP Change order of packed
3878 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3879 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3880 PNG_TRANSFORM_SHIFT Normalize pixels to the
3881 sBIT depth
3882 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
3883 to BGRA
3884 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
3885 to AG
3886 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
3887 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3888 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
Glenn Randers-Pehrson1eb14e92008-12-10 07:14:45 -0600[diff] [blame]3889 PNG_TRANSFORM_STRIP_FILLER Strip out filler
3890 bytes (deprecated).
3891 PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
3892 filler bytes
3893 PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
3894 filler bytes
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3895
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3896If you have valid image data in the info structure (you can use
3897png_set_rows() to put image data in the info structure), simply do this:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3898
3899 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
3900
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3901where png_transforms is an integer containing the bitwise OR of some set of
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3902transformation flags. This call is equivalent to png_write_info(),
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3903followed the set of transformations indicated by the transform mask,
3904then png_write_image(), and finally png_write_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3905
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3906(The final parameter of this call is not yet used. Someday it might point
3907to transformation parameters required by some future output transform.)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3908
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]3909You must use png_transforms and not call any png_set_transform() functions
3910when you use png_write_png().
3911
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3912.SS The low-level write interface
3913
3914If you are going the low-level route instead, you are now ready to
3915write all the file information up to the actual image data. You do
3916this with a call to png_write_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3917
3918 png_write_info(png_ptr, info_ptr);
3919
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3920Note that there is one transformation you may need to do before
3921png_write_info(). In PNG files, the alpha channel in an image is the
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3922level of opacity. If your data is supplied as a level of transparency,
3923you can invert the alpha channel before you write it, so that 0 is
3924fully transparent and 255 (in 8-bit or paletted images) or 65535
3925(in 16-bit images) is fully opaque, with
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3926
3927 png_set_invert_alpha(png_ptr);
3928
3929This must appear before png_write_info() instead of later with the
3930other transformations because in the case of paletted images the tRNS
3931chunk data has to be inverted before the tRNS chunk is written. If
3932your image is not a paletted image, the tRNS data (which in such cases
3933represents a single color to be rendered as transparent) won't need to
3934be changed, and you can safely do this transformation after your
3935png_write_info() call.
3936
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]3937If you need to write a private chunk that you want to appear before
3938the PLTE chunk when PLTE is present, you can write the PNG info in
3939two steps, and insert code to write your own chunk between them:
3940
3941 png_write_info_before_PLTE(png_ptr, info_ptr);
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3942 png_set_unknown_chunks(png_ptr, info_ptr, ...);
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]3943 png_write_info(png_ptr, info_ptr);
3944
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3945After you've written the file information, you can set up the library
3946to handle any special transformations of the image data. The various
3947ways to transform the data will be described in the order that they
3948should occur. This is important, as some of these change the color
3949type and/or bit depth of the data, and some others only work on
3950certain color types and bit depths. Even though each transformation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3951checks to see if it has data that it can do something with, you should
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3952make sure to only enable a transformation if it will be valid for the
3953data. For example, don't swap red and blue on grayscale data.
3954
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3955PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]3956the library to strip input data that has 4 or 8 bytes per pixel down
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3957to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
3958bytes per pixel).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3959
3960 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
3961
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3962where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3963PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
3964is stored XRGB or RGBX.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3965
3966PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
3967they can, resulting in, for example, 8 pixels per byte for 1 bit files.
3968If the data is supplied at 1 pixel per byte, use this code, which will
3969correctly pack the pixels into a single byte:
3970
3971 png_set_packing(png_ptr);
3972
3973PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
3974data is of another bit depth, you can write an sBIT chunk into the
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3975file so that decoders can recover the original data if desired.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3976
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3977 /* Set the true bit depth of the image data */
3978 if (color_type & PNG_COLOR_MASK_COLOR)
3979 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3980 sig_bit.red = true_bit_depth;
3981 sig_bit.green = true_bit_depth;
3982 sig_bit.blue = true_bit_depth;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3983 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3984
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3985 else
3986 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3987 sig_bit.gray = true_bit_depth;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3988 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3989
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3990 if (color_type & PNG_COLOR_MASK_ALPHA)
3991 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3992 sig_bit.alpha = true_bit_depth;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3993 }
3994
3995 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
3996
3997If the data is stored in the row buffer in a bit depth other than
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3998one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3999this will scale the values to appear to be the correct bit depth as
4000is required by PNG.
4001
4002 png_set_shift(png_ptr, &sig_bit);
4003
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]4004PNG files store 16-bit pixels in network byte order (big-endian,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4005ie. most significant bits first). This code would be used if they are
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4006supplied the other way (little-endian, i.e. least significant bits
4007first, the way PCs store them):
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4008
4009 if (bit_depth > 8)
4010 png_set_swap(png_ptr);
4011
4012If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
4013need to change the order the pixels are packed into bytes, you can use:
4014
4015 if (bit_depth < 8)
4016 png_set_packswap(png_ptr);
4017
4018PNG files store 3 color pixels in red, green, blue order. This code
4019would be used if they are supplied as blue, green, red:
4020
4021 png_set_bgr(png_ptr);
4022
4023PNG files describe monochrome as black being zero and white being
4024one. This code would be used if the pixels are supplied with this reversed
4025(black being one and white being zero):
4026
4027 png_set_invert_mono(png_ptr);
4028
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]4029Finally, you can write your own transformation function if none of
4030the existing ones meets your needs. This is done by setting a callback
4031with
4032
4033 png_set_write_user_transform_fn(png_ptr,
4034 write_transform_fn);
4035
4036You must supply the function
4037
Glenn Randers-Pehrson93215672011-02-13 19:42:19 -0600[diff] [blame]4038 void write_transform_fn(png_structp png_ptr, png_row_infop
4039 row_info, png_bytep data)
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]4040
4041See pngtest.c for a working example. Your function will be called
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]4042before any of the other transformations are processed. If supported
4043libpng also supplies an information routine that may be called from
4044your callback:
4045
4046 png_get_current_row_number(png_ptr);
John Bowlercd113452011-02-16 06:15:13 -0600[diff] [blame]4047 png_get_current_pass_number(png_ptr);
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]4048
John Bowlercd113452011-02-16 06:15:13 -0600[diff] [blame]4049This returns the current row passed to the transform. With interlaced
4050images the value returned is the row in the input sub-image image. Use
4051PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
4052find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
4053
4054The discussion of interlace handling above contains more information on how to
4055use these values.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]4056
4057You can also set up a pointer to a user structure for use by your
4058callback function.
4059
4060 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
4061
4062The user_channels and user_depth parameters of this function are ignored
4063when writing; you can set them to zero as shown.
4064
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4065You can retrieve the pointer via the function png_get_user_transform_ptr().
4066For example:
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]4067
4068 voidp write_user_transform_ptr =
4069 png_get_user_transform_ptr(png_ptr);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]4070
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4071It is possible to have libpng flush any pending output, either manually,
4072or automatically after a certain number of lines have been written. To
4073flush the output stream a single time call:
4074
4075 png_write_flush(png_ptr);
4076
4077and to have libpng flush the output stream periodically after a certain
4078number of scanlines have been written, call:
4079
4080 png_set_flush(png_ptr, nrows);
4081
4082Note that the distance between rows is from the last time png_write_flush()
4083was called, or the first row of the image if it has never been called.
4084So if you write 50 lines, and then png_set_flush 25, it will flush the
4085output on the next scanline, and every 25 lines thereafter, unless
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4086png_write_flush() is called before 25 more lines have been written.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4087If nrows is too small (less than about 10 lines for a 640 pixel wide
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4088RGB image) the image compression may decrease noticeably (although this
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4089may be acceptable for real-time applications). Infrequent flushing will
4090only degrade the compression performance by a few percent over images
4091that do not use flushing.
4092
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4093.SS Writing the image data
4094
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4095That's it for the transformations. Now you can write the image data.
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]4096The simplest way to do this is in one function call. If you have the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4097whole image in memory, you can just call png_write_image() and libpng
4098will write the image. You will need to pass in an array of pointers to
4099each row. This function automatically handles interlacing, so you don't
4100need to call png_set_interlace_handling() or call this function multiple
4101times, or any of that other stuff necessary with png_write_rows().
4102
4103 png_write_image(png_ptr, row_pointers);
4104
4105where row_pointers is:
4106
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]4107 png_byte *row_pointers[height];
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4108
4109You can point to void or char or whatever you use for pixels.
4110
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]4111If you don't want to write the whole image at once, you can
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4112use png_write_rows() instead. If the file is not interlaced,
4113this is simple:
4114
4115 png_write_rows(png_ptr, row_pointers,
4116 number_of_rows);
4117
4118row_pointers is the same as in the png_write_image() call.
4119
4120If you are just writing one row at a time, you can do this with
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]4121a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4122
4123 png_bytep row_pointer = row;
4124
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]4125 png_write_row(png_ptr, row_pointer);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4126
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4127When the file is interlaced, things can get a good deal more complicated.
4128The only currently (as of the PNG Specification version 1.2, dated July
41291999) defined interlacing scheme for PNG files is the "Adam7" interlace
4130scheme, that breaks down an image into seven smaller images of varying
4131size. libpng will build these images for you, or you can do them
4132yourself. If you want to build them yourself, see the PNG specification
4133for details of which pixels to write when.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4134
4135If you don't want libpng to handle the interlacing details, just
4136use png_set_interlace_handling() and call png_write_rows() the
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]4137correct number of times to write all the sub-images
4138(png_set_interlace_handling() returns the number of sub-images.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4139
4140If you want libpng to build the sub-images, call this before you start
4141writing any rows:
4142
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]4143 number_of_passes = png_set_interlace_handling(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4144
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4145This will return the number of passes needed. Currently, this is seven,
4146but may change if another interlace type is added.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4147
4148Then write the complete image number_of_passes times.
4149
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]4150 png_write_rows(png_ptr, row_pointers, number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4151
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]4152Think carefully before you write an interlaced image. Typically code that
4153reads such images reads all the image data into memory, uncompressed, before
4154doing any processing. Only code that can display an image on the fly can
4155take advantage of the interlacing and even then the image has to be exactly
4156the correct size for the output device, because scaling an image requires
4157adjacent pixels and these are not available until all the passes have been
4158read.
4159
4160If you do write an interlaced image you will hardly ever need to handle
4161the interlacing yourself. Call png_set_interlace_handling() and use the
4162approach described above.
4163
4164The only time it is conceivable that you will really need to write an
4165interlaced image pass-by-pass is when you have read one pass by pass and
4166made some pixel-by-pixel transformation to it, as described in the read
4167code above. In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros
4168to determine the size of each sub-image in turn and simply write the rows
4169you obtained from the read code.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4170
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4171.SS Finishing a sequential write
4172
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4173After you are finished writing the image, you should finish writing
4174the file. If you are interested in writing comments or time, you should
4175pass an appropriately filled png_info pointer. If you are not interested,
4176you can pass NULL.
4177
4178 png_write_end(png_ptr, info_ptr);
4179
4180When you are done, you can free all memory used by libpng like this:
4181
4182 png_destroy_write_struct(&png_ptr, &info_ptr);
4183
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]4184It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]4185point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]4186
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]4187 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4188
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4189 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4190 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4191 more of
4192 PNG_FREE_PLTE, PNG_FREE_TRNS,
4193 PNG_FREE_HIST, PNG_FREE_ICCP,
4194 PNG_FREE_PCAL, PNG_FREE_ROWS,
4195 PNG_FREE_SCAL, PNG_FREE_SPLT,
4196 PNG_FREE_TEXT, PNG_FREE_UNKN,
4197 or simply PNG_FREE_ALL
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4198
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]4199 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4200 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]4201
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]4202This function may be safely called when the relevant storage has
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4203already been freed, or has not yet been allocated, or was allocated
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4204by the user and not by libpng, and will in those cases do nothing.
4205The "seq" parameter is ignored if only one item of the selected data
4206type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
4207are allowed for the data type identified in the mask, such as text or
4208sPLT, only the n'th item in the structure is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]4209
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4210If you allocated data such as a palette that you passed in to libpng
4211with png_set_*, you must not free it until just before the call to
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]4212png_destroy_write_struct().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4213
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4214The default behavior is only to free data that was allocated internally
4215by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4216or so that it will free data that was allocated by the user with png_malloc()
4217or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4218
4219 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4220
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4221 freer - one of
4222 PNG_DESTROY_WILL_FREE_DATA
4223 PNG_SET_WILL_FREE_DATA
4224 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4225
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4226 mask - which data elements are affected
4227 same choices as in png_free_data()
4228
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4229For example, to transfer responsibility for some data from a read structure
4230to a write structure, you could use
4231
4232 png_data_freer(read_ptr, read_info_ptr,
4233 PNG_USER_WILL_FREE_DATA,
4234 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4235
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4236 png_data_freer(write_ptr, write_info_ptr,
4237 PNG_DESTROY_WILL_FREE_DATA,
4238 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
4239
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4240thereby briefly reassigning responsibility for freeing to the user but
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4241immediately afterwards reassigning it once more to the write_destroy
4242function. Having done this, it would then be safe to destroy the read
4243structure and continue to use the PLTE, tRNS, and hIST data in the write
4244structure.
4245
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4246This function only affects data that has already been allocated.
4247You can call this function before calling after the png_set_*() functions
4248to control whether the user or png_destroy_*() is supposed to free the data.
4249When the user assumes responsibility for libpng-allocated data, the
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4250application must use
4251png_free() to free it, and when the user transfers responsibility to libpng
4252for data that the user has allocated, the user must have used png_malloc()
4253or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4254
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4255If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
4256separately, do not transfer responsibility for freeing text_ptr to libpng,
4257because when libpng fills a png_text structure it combines these members with
4258the key member, and png_free_data() will free only text_ptr.key. Similarly,
4259if you transfer responsibility for free'ing text_ptr from libpng to your
4260application, your application must not separately free those members.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4261For a more compact example of writing a PNG image, see the file example.c.
4262
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4263.SH V. Modifying/Customizing libpng:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4264
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4265There are two issues here. The first is changing how libpng does
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4266standard things like memory allocation, input/output, and error handling.
4267The second deals with more complicated things like adding new chunks,
4268adding new transformations, and generally changing how libpng works.
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]4269Both of those are compile-time issues; that is, they are generally
4270determined at the time the code is written, and there is rarely a need
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4271to provide the user with a means of changing them.
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]4272
4273Memory allocation, input/output, and error handling
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4274
4275All of the memory allocation, input/output, and error handling in libpng
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]4276goes through callbacks that are user-settable. The default routines are
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4277in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]4278these functions, call the appropriate png_set_*_fn() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4279
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4280Memory allocation is done through the functions png_malloc(), png_calloc(),
4281and png_free(). These currently just call the standard C functions.
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]4282png_calloc() calls png_malloc() and then clears the newly
4283allocated memory to zero. There is limited support for certain systems
4284with segmented memory architectures and the types of pointers declared by
4285png.h match this; you will have to use appropriate pointers in your
4286application. Since it is
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4287unlikely that the method of handling memory allocation on a platform
4288will change between applications, these functions must be modified in
4289the library at compile time. If you prefer to use a different method
4290of allocating and freeing data, you can use png_create_read_struct_2() or
4291png_create_write_struct_2() to register your own functions as described
4292above. These functions also provide a void pointer that can be retrieved
4293via
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4294
4295 mem_ptr=png_get_mem_ptr(png_ptr);
4296
4297Your replacement memory functions must have prototypes as follows:
4298
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]4299 png_voidp malloc_fn(png_structp png_ptr,
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4300 png_alloc_size_t size);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4301
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4302 void free_fn(png_structp png_ptr, png_voidp ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4303
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]4304Your malloc_fn() must return NULL in case of failure. The png_malloc()
4305function will normally call png_error() if it receives a NULL from the
4306system memory allocator or from your replacement malloc_fn().
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]4307
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4308Your free_fn() will never be called with a NULL ptr, since libpng's
4309png_free() checks for NULL before calling free_fn().
4310
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4311Input/Output in libpng is done through png_read() and png_write(),
4312which currently just call fread() and fwrite(). The FILE * is stored in
4313png_struct and is initialized via png_init_io(). If you wish to change
4314the method of I/O, the library supplies callbacks that you can set
4315through the function png_set_read_fn() and png_set_write_fn() at run
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4316time, instead of calling the png_init_io() function. These functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4317also provide a void pointer that can be retrieved via the function
4318png_get_io_ptr(). For example:
4319
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]4320 png_set_read_fn(png_structp read_ptr,
4321 voidp read_io_ptr, png_rw_ptr read_data_fn)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4322
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]4323 png_set_write_fn(png_structp write_ptr,
4324 voidp write_io_ptr, png_rw_ptr write_data_fn,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4325 png_flush_ptr output_flush_fn);
4326
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]4327 voidp read_io_ptr = png_get_io_ptr(read_ptr);
4328 voidp write_io_ptr = png_get_io_ptr(write_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4329
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4330The replacement I/O functions must have prototypes as follows:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4331
4332 void user_read_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]4333 png_bytep data, png_size_t length);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4334
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4335 void user_write_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]4336 png_bytep data, png_size_t length);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4337
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4338 void user_flush_data(png_structp png_ptr);
4339
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4340The user_read_data() function is responsible for detecting and
4341handling end-of-data errors.
4342
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4343Supplying NULL for the read, write, or flush functions sets them back
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4344to using the default C stream functions, which expect the io_ptr to
4345point to a standard *FILE structure. It is probably a mistake
4346to use NULL for one of write_data_fn and output_flush_fn but not both
4347of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
4348It is an error to read from a write stream, and vice versa.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4349
4350Error handling in libpng is done through png_error() and png_warning().
4351Errors handled through png_error() are fatal, meaning that png_error()
4352should never return to its caller. Currently, this is handled via
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4353setjmp() and longjmp() (unless you have compiled libpng with
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]4354PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
Glenn Randers-Pehrson60988072010-04-13 22:11:06 -0500[diff] [blame]4355but you could change this to do things like exit() if you should wish,
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]4356as long as your function does not return.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4357
4358On non-fatal errors, png_warning() is called
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4359to print a warning message, and then control returns to the calling code.
4360By default png_error() and png_warning() print a message on stderr via
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4361fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
4362(because you don't want the messages) or PNG_NO_STDIO defined (because
4363fprintf() isn't available). If you wish to change the behavior of the error
4364functions, you will need to set up your own message callbacks. These
4365functions are normally supplied at the time that the png_struct is created.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4366It is also possible to redirect errors and warnings to your own replacement
4367functions after png_create_*_struct() has been called by calling:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4368
4369 png_set_error_fn(png_structp png_ptr,
4370 png_voidp error_ptr, png_error_ptr error_fn,
4371 png_error_ptr warning_fn);
4372
4373 png_voidp error_ptr = png_get_error_ptr(png_ptr);
4374
4375If NULL is supplied for either error_fn or warning_fn, then the libpng
4376default function will be used, calling fprintf() and/or longjmp() if a
4377problem is encountered. The replacement error functions should have
4378parameters as follows:
4379
4380 void user_error_fn(png_structp png_ptr,
4381 png_const_charp error_msg);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4382
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4383 void user_warning_fn(png_structp png_ptr,
4384 png_const_charp warning_msg);
4385
4386The motivation behind using setjmp() and longjmp() is the C++ throw and
4387catch exception handling methods. This makes the code much easier to write,
4388as there is no need to check every return code of every function call.
4389However, there are some uncertainties about the status of local variables
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4390after a longjmp, so the user may want to be careful about doing anything
4391after setjmp returns non-zero besides returning itself. Consult your
4392compiler documentation for more details. For an alternative approach, you
4393may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4394
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4395.SS Custom chunks
4396
4397If you need to read or write custom chunks, you may need to get deeper
4398into the libpng code. The library now has mechanisms for storing
4399and writing chunks of unknown type; you can even declare callbacks
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]4400for custom chunks. However, this may not be good enough if the
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4401library code itself needs to know about interactions between your
4402chunk and existing `intrinsic' chunks.
4403
4404If you need to write a new intrinsic chunk, first read the PNG
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4405specification. Acquire a first level of understanding of how it works.
4406Pay particular attention to the sections that describe chunk names,
4407and look at how other chunks were designed, so you can do things
4408similarly. Second, check out the sections of libpng that read and
4409write chunks. Try to find a chunk that is similar to yours and use
4410it as a template. More details can be found in the comments inside
4411the code. It is best to handle unknown chunks in a generic method,
4412via callback functions, instead of by modifying libpng functions.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4413
4414If you wish to write your own transformation for the data, look through
4415the part of the code that does the transformations, and check out some of
4416the simpler ones to get an idea of how they work. Try to find a similar
4417transformation to the one you want to add and copy off of it. More details
4418can be found in the comments inside the code itself.
4419
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]4420.SS Configuring for 16-bit platforms
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4421
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4422You will want to look into zconf.h to tell zlib (and thus libpng) that
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4423it cannot allocate more then 64K at a time. Even if you can, the memory
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4424won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4425
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4426.SS Configuring for DOS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4427
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4428For DOS users who only have access to the lower 640K, you will
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4429have to limit zlib's memory usage via a png_set_compression_mem_level()
4430call. See zlib.h or zconf.h in the zlib library for more information.
4431
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4432.SS Configuring for Medium Model
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4433
4434Libpng's support for medium model has been tested on most of the popular
4435compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
4436defined, and FAR gets defined to far in pngconf.h, and you should be
4437all set. Everything in the library (except for zlib's structure) is
4438expecting far data. You must use the typedefs with the p or pp on
4439the end for pointers (or at least look at them and be careful). Make
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4440note that the rows of data are defined as png_bytepp, which is an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4441unsigned char far * far *.
4442
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4443.SS Configuring for gui/windowing platforms:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4444
4445You will need to write new error and warning functions that use the GUI
4446interface, as described previously, and set them to be the error and
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]4447warning functions at the time that png_create_*_struct() is called,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4448in order to have them available during the structure initialization.
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4449They can be changed later via png_set_error_fn(). On some compilers,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4450you may also have to change the memory allocators (png_malloc, etc.).
4451
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4452.SS Configuring for compiler xxx:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4453
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]4454All includes for libpng are in pngconf.h. If you need to add, change
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4455or delete an include, this is the place to do it.
4456The includes that are not needed outside libpng are placed in pngpriv.h,
4457which is only used by the routines inside libpng itself.
4458The files in libpng proper only include pngpriv.h and png.h, which
4459in turn includes pngconf.h.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4460
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4461.SS Configuring zlib:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4462
4463There are special functions to configure the compression. Perhaps the
4464most useful one changes the compression level, which currently uses
4465input compression values in the range 0 - 9. The library normally
4466uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
4467have shown that for a large majority of images, compression values in
4468the range 3-6 compress nearly as well as higher levels, and do so much
4469faster. For online applications it may be desirable to have maximum speed
4470(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
4471specify no compression (Z_NO_COMPRESSION = 0), but this would create
4472files larger than just storing the raw bitmap. You can specify the
4473compression level by calling:
4474
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]4475 #include zlib.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4476 png_set_compression_level(png_ptr, level);
4477
4478Another useful one is to reduce the memory level used by the library.
4479The memory level defaults to 8, but it can be lowered if you are
4480short on memory (running DOS, for example, where you only have 640K).
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4481Note that the memory level does have an effect on compression; among
4482other things, lower levels will result in sections of incompressible
4483data being emitted in smaller stored blocks, with a correspondingly
4484larger relative overhead of up to 15% in the worst case.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4485
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]4486 #include zlib.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4487 png_set_compression_mem_level(png_ptr, level);
4488
4489The other functions are for configuring zlib. They are not recommended
4490for normal use and may result in writing an invalid PNG file. See
4491zlib.h for more information on what these mean.
4492
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]4493 #include zlib.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4494 png_set_compression_strategy(png_ptr,
4495 strategy);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4496
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4497 png_set_compression_window_bits(png_ptr,
4498 window_bits);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4499
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4500 png_set_compression_method(png_ptr, method);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4501 png_set_compression_buffer_size(png_ptr, size);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4502
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4503.SS Controlling row filtering
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4504
4505If you want to control whether libpng uses filtering or not, which
4506filters are used, and how it goes about picking row filters, you
4507can call one of these functions. The selection and configuration
4508of row filters can have a significant impact on the size and
4509encoding speed and a somewhat lesser impact on the decoding speed
4510of an image. Filtering is enabled by default for RGB and grayscale
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4511images (with and without alpha), but not for paletted images nor
4512for any images with bit depths less than 8 bits/pixel.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4513
4514The 'method' parameter sets the main filtering method, which is
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]4515currently only '0' in the PNG 1.2 specification. The 'filters'
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4516parameter sets which filter(s), if any, should be used for each
4517scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
4518to turn filtering on and off, respectively.
4519
4520Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
4521PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4522ORed together with '|' to specify one or more filters to use.
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4523These filters are described in more detail in the PNG specification.
4524If you intend to change the filter type during the course of writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4525the image, you should start with flags set for all of the filters
4526you intend to use so that libpng can initialize its internal
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4527structures appropriately for all of the filter types. (Note that this
4528means the first row must always be adaptively filtered, because libpng
4529currently does not allocate the filter buffers until png_write_row()
4530is called for the first time.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4531
4532 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]4533 PNG_FILTER_UP | PNG_FILTER_AVG |
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4534 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4535
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4536 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
4537 filters);
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]4538 The second parameter can also be
4539 PNG_INTRAPIXEL_DIFFERENCING if you are
4540 writing a PNG to be embedded in a MNG
4541 datastream. This parameter must be the
4542 same as the value of filter_method used
4543 in png_set_IHDR().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4544
4545It is also possible to influence how libpng chooses from among the
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4546available filters. This is done in one or both of two ways - by
4547telling it how important it is to keep the same filter for successive
4548rows, and by telling it the relative computational costs of the filters.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4549
4550 double weights[3] = {1.5, 1.3, 1.1},
4551 costs[PNG_FILTER_VALUE_LAST] =
4552 {1.0, 1.3, 1.3, 1.5, 1.7};
4553
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4554 png_set_filter_heuristics(png_ptr,
4555 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4556 weights, costs);
4557
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4558The weights are multiplying factors that indicate to libpng that the
4559row filter should be the same for successive rows unless another row filter
4560is that many times better than the previous filter. In the above example,
4561if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4562"sum of absolute differences" 1.5 x 1.3 times higher than other filters
4563and still be chosen, while the NONE filter could have a sum 1.1 times
4564higher than other filters and still be chosen. Unspecified weights are
4565taken to be 1.0, and the specified weights should probably be declining
4566like those above in order to emphasize recent filters over older filters.
4567
4568The filter costs specify for each filter type a relative decoding cost
4569to be considered when selecting row filters. This means that filters
4570with higher costs are less likely to be chosen over filters with lower
4571costs, unless their "sum of absolute differences" is that much smaller.
4572The costs do not necessarily reflect the exact computational speeds of
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4573the various filters, since this would unduly influence the final image
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4574size.
4575
4576Note that the numbers above were invented purely for this example and
4577are given only to help explain the function usage. Little testing has
4578been done to find optimum values for either the costs or the weights.
4579
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4580.SS Removing unwanted object code
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4581
4582There are a bunch of #define's in pngconf.h that control what parts of
4583libpng are compiled. All the defines end in _SUPPORTED. If you are
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]4584never going to use a capability, you can change the #define to #undef
4585before recompiling libpng and save yourself code and data space, or
4586you can turn off individual capabilities with defines that begin with
4587PNG_NO_.
4588
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4589In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
4590
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]4591You can also turn all of the transforms and ancillary chunk capabilities
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4592off en masse with compiler directives that define
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]4593PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
4594or all four,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4595along with directives to turn on any of the capabilities that you do
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4596want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
4597transformations but still leave the library fully capable of reading
4598and writing PNG files with all known public chunks. Use of the
4599PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
4600that is incapable of reading or writing ancillary chunks. If you are
4601not using the progressive reading capability, you can turn that off
4602with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
4603capability, which you'll still have).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4604
4605All the reading and writing specific code are in separate files, so the
4606linker should only grab the files it needs. However, if you want to
4607make sure, or if you are building a stand alone library, all the
4608reading files start with pngr and all the writing files start with
4609pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
4610are used for both reading and writing, and always need to be included.
4611The progressive reader is in pngpread.c
4612
4613If you are creating or distributing a dynamically linked library (a .so
4614or DLL file), you should not remove or disable any parts of the library,
4615as this will cause applications linked with different versions of the
4616library to fail if they call functions not available in your library.
4617The size of the library itself should not be an issue, because only
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4618those sections that are actually used will be loaded into memory.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4619
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4620.SS Requesting debug printout
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4621
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4622The macro definition PNG_DEBUG can be used to request debugging
4623printout. Set it to an integer value in the range 0 to 3. Higher
4624numbers result in increasing amounts of debugging information. The
4625information is printed to the "stderr" file, unless another file
4626name is specified in the PNG_DEBUG_FILE macro definition.
4627
4628When PNG_DEBUG > 0, the following functions (macros) become available:
4629
4630 png_debug(level, message)
4631 png_debug1(level, message, p1)
4632 png_debug2(level, message, p1, p2)
4633
4634in which "level" is compared to PNG_DEBUG to decide whether to print
4635the message, "message" is the formatted string to be printed,
4636and p1 and p2 are parameters that are to be embedded in the string
4637according to printf-style formatting directives. For example,
4638
4639 png_debug1(2, "foo=%d\n", foo);
4640
4641is expanded to
4642
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4643 if (PNG_DEBUG > 2)
4644 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4645
4646When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
4647can still use PNG_DEBUG to control your own debugging:
4648
4649 #ifdef PNG_DEBUG
4650 fprintf(stderr, ...
4651 #endif
4652
4653When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
4654having level = 0 will be printed. There aren't any such statements in
4655this version of libpng, but if you insert some they will be printed.
4656
Glenn Randers-Pehrson56f63962008-10-06 10:16:17 -0500[diff] [blame]4657.SH VI. MNG support
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]4658
4659The MNG specification (available at http://www.libpng.org/pub/mng) allows
4660certain extensions to PNG for PNG images that are embedded in MNG datastreams.
4661Libpng can support some of these extensions. To enable them, use the
4662png_permit_mng_features() function:
4663
4664 feature_set = png_permit_mng_features(png_ptr, mask)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4665
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4666 mask is a png_uint_32 containing the bitwise OR of the
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]4667 features you want to enable. These include
4668 PNG_FLAG_MNG_EMPTY_PLTE
4669 PNG_FLAG_MNG_FILTER_64
4670 PNG_ALL_MNG_FEATURES
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4671
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4672 feature_set is a png_uint_32 that is the bitwise AND of
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]4673 your mask with the set of MNG features that is
4674 supported by the version of libpng that you are using.
4675
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]4676It is an error to use this function when reading or writing a standalone
4677PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
Glenn Randers-Pehrsonf05f8032000-12-23 14:27:39 -0600[diff] [blame]4678in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
4679and the MHDR and MEND chunks. Libpng does not provide support for these
4680or any other MNG chunks; your application must provide its own support for
4681them. You may wish to consider using libmng (available at
4682http://www.libmng.com) instead.
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]4683
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4684.SH VII. Changes to Libpng from version 0.88
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4685
4686It should be noted that versions of libpng later than 0.96 are not
4687distributed by the original libpng author, Guy Schalnat, nor by
4688Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
4689distributed versions 0.89 through 0.96, but rather by another member
4690of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
4691still alive and well, but they have moved on to other things.
4692
4693The old libpng functions png_read_init(), png_write_init(),
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]4694png_info_init(), png_read_destroy(), and png_write_destroy() have been
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]4695moved to PNG_INTERNAL in version 0.95 to discourage their use. These
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4696functions will be removed from libpng version 1.4.0.
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]4697
4698The preferred method of creating and initializing the libpng structures is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4699via the png_create_read_struct(), png_create_write_struct(), and
4700png_create_info_struct() because they isolate the size of the structures
4701from the application, allow version error checking, and also allow the
4702use of custom error handling routines during the initialization, which
4703the old functions do not. The functions png_read_destroy() and
4704png_write_destroy() do not actually free the memory that libpng
4705allocated for these structs, but just reset the data structures, so they
4706can be used instead of png_destroy_read_struct() and
4707png_destroy_write_struct() if you feel there is too much system overhead
4708allocating and freeing the png_struct for each image read.
4709
4710Setting the error callbacks via png_set_message_fn() before
4711png_read_init() as was suggested in libpng-0.88 is no longer supported
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4712because this caused applications that do not use custom error functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4713to fail if the png_ptr was not initialized to zero. It is still possible
4714to set the error callbacks AFTER png_read_init(), or to change them with
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]4715png_set_error_fn(), which is essentially the same function, but with a new
4716name to force compilation errors with applications that try to use the old
4717method.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4718
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4719Starting with version 1.0.7, you can find out which version of the library
4720you are using at run-time:
4721
4722 png_uint_32 libpng_vn = png_access_version_number();
4723
4724The number libpng_vn is constructed from the major version, minor
4725version with leading zero, and release number with leading zero,
4726(e.g., libpng_vn for version 1.0.7 is 10007).
4727
4728You can also check which version of png.h you used when compiling your
4729application:
4730
4731 png_uint_32 application_vn = PNG_LIBPNG_VER;
4732
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4733.SH VIII. Changes to Libpng from version 1.0.x to 1.2.x
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]4734
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4735Support for user memory management was enabled by default. To
4736accomplish this, the functions png_create_read_struct_2(),
4737png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
4738png_malloc_default(), and png_free_default() were added.
4739
Glenn Randers-Pehrsond6ea40a2009-11-02 07:32:00 -0600[diff] [blame]4740Support for the iTXt chunk has been enabled by default as of
4741version 1.2.41.
4742
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4743Support for certain MNG features was enabled.
4744
4745Support for numbered error messages was added. However, we never got
4746around to actually numbering the error messages. The function
4747png_set_strip_error_numbers() was added (Note: the prototype for this
4748function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
4749builds of libpng-1.2.15. It was restored in libpng-1.2.36).
4750
4751The png_malloc_warn() function was added at libpng-1.2.3. This issues
4752a png_warning and returns NULL instead of aborting when it fails to
4753acquire the requested memory allocation.
4754
4755Support for setting user limits on image width and height was enabled
4756by default. The functions png_set_user_limits(), png_get_user_width_max(),
4757and png_get_user_height_max() were added at libpng-1.2.6.
4758
4759The png_set_add_alpha() function was added at libpng-1.2.7.
4760
4761The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
4762Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
4763tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
4764deprecated.
4765
4766A number of macro definitions in support of runtime selection of
4767assembler code features (especially Intel MMX code support) were
4768added at libpng-1.2.0:
4769
4770 PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
4771 PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
4772 PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
4773 PNG_ASM_FLAG_MMX_READ_INTERLACE
4774 PNG_ASM_FLAG_MMX_READ_FILTER_SUB
4775 PNG_ASM_FLAG_MMX_READ_FILTER_UP
4776 PNG_ASM_FLAG_MMX_READ_FILTER_AVG
4777 PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
4778 PNG_ASM_FLAGS_INITIALIZED
4779 PNG_MMX_READ_FLAGS
4780 PNG_MMX_FLAGS
4781 PNG_MMX_WRITE_FLAGS
4782 PNG_MMX_FLAGS
4783
4784We added the following functions in support of runtime
4785selection of assembler code features:
4786
4787 png_get_mmx_flagmask()
4788 png_set_mmx_thresholds()
4789 png_get_asm_flags()
4790 png_get_mmx_bitdepth_threshold()
4791 png_get_mmx_rowbytes_threshold()
4792 png_set_asm_flags()
4793
4794We replaced all of these functions with simple stubs in libpng-1.2.20,
4795when the Intel assembler code was removed due to a licensing issue.
4796
Glenn Randers-Pehrson3d893a02009-08-31 13:32:46 -0500[diff] [blame]4797These macros are deprecated:
4798
4799 PNG_READ_TRANSFORMS_NOT_SUPPORTED
4800 PNG_PROGRESSIVE_READ_NOT_SUPPORTED
4801 PNG_NO_SEQUENTIAL_READ_SUPPORTED
4802 PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
4803 PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
4804 PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
4805
4806They have been replaced, respectively, by:
4807
4808 PNG_NO_READ_TRANSFORMS
4809 PNG_NO_PROGRESSIVE_READ
4810 PNG_NO_SEQUENTIAL_READ
4811 PNG_NO_WRITE_TRANSFORMS
4812 PNG_NO_READ_ANCILLARY_CHUNKS
4813 PNG_NO_WRITE_ANCILLARY_CHUNKS
4814
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4815PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
4816deprecated since libpng-1.0.16 and libpng-1.2.6.
4817
4818The function
4819 png_check_sig(sig, num)
4820was replaced with
4821 !png_sig_cmp(sig, 0, num)
4822It has been deprecated since libpng-0.90.
4823
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4824The function
4825 png_set_gray_1_2_4_to_8()
4826which also expands tRNS to alpha was replaced with
4827 png_set_expand_gray_1_2_4_to_8()
4828which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4829
Glenn Randers-Pehrsond740c842009-11-04 19:01:54 -0600[diff] [blame]4830.SH IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
4831
4832Private libpng prototypes and macro definitions were moved from
4833png.h and pngconf.h into a new pngpriv.h header file.
4834
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4835Functions png_set_benign_errors(), png_benign_error(), and
4836png_chunk_benign_error() were added.
4837
4838Support for setting the maximum amount of memory that the application
4839will allocate for reading chunks was added, as a security measure.
4840The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
4841were added to the library.
4842
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4843We implemented support for I/O states by adding png_ptr member io_state
4844and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4845
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]4846We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
4847input transforms.
4848
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]4849Checking for and reporting of errors in the IHDR chunk is more thorough.
4850
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4851Support for global arrays was removed, to improve thread safety.
4852
4853Some obsolete/deprecated macros and functions have been removed.
4854
4855Typecasted NULL definitions such as
4856 #define png_voidp_NULL (png_voidp)NULL
4857were eliminated. If you used these in your application, just use
4858NULL instead.
4859
4860The png_struct and info_struct members "trans" and "trans_values" were
4861changed to "trans_alpha" and "trans_color", respectively.
4862
4863The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4864were removed.
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4865
4866The PNG_1_0_X and PNG_1_2_X macros were eliminated.
4867
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]4868The PNG_LEGACY_SUPPORTED macro was eliminated.
4869
4870Many WIN32_WCE #ifdefs were removed.
4871
4872The functions png_read_init(info_ptr), png_write_init(info_ptr),
4873png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
4874have been removed. They have been deprecated since libpng-0.95.
4875
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4876The png_permit_empty_plte() was removed. It has been deprecated
4877since libpng-1.0.9. Use png_permit_mng_features() instead.
4878
4879We removed the obsolete stub functions png_get_mmx_flagmask(),
4880png_set_mmx_thresholds(), png_get_asm_flags(),
4881png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
4882png_set_asm_flags(), and png_mmx_supported()
4883
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4884We removed the obsolete png_check_sig(), png_memcpy_check(), and
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]4885png_memset_check() functions. Instead use !png_sig_cmp(), memcpy(),
4886and memset(), respectively.
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4887
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4888The function png_set_gray_1_2_4_to_8() was removed. It has been
4889deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
4890png_set_expand_gray_1_2_4_to_8() because the former function also
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4891expanded any tRNS chunk to an alpha channel.
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4892
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4893Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
4894were added and are used by default instead of the corresponding
4895functions. Unfortunately,
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4896from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4897function) incorrectly returned a value of type png_uint_32.
4898
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4899We changed the prototype for png_malloc() from
4900 png_malloc(png_structp png_ptr, png_uint_32 size)
4901to
4902 png_malloc(png_structp png_ptr, png_alloc_size_t size)
4903
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4904This also applies to the prototype for the user replacement malloc_fn().
4905
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4906The png_calloc() function was added and is used in place of
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]4907of "png_malloc(); memset();" except in the case in png_read_png()
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4908where the array consists of pointers; in this case a "for" loop is used
4909after the png_malloc() to set the pointers to NULL, to give robust.
4910behavior in case the application runs out of memory part-way through
4911the process.
4912
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4913We changed the prototypes of png_get_compression_buffer_size() and
4914png_set_compression_buffer_size() to work with png_size_t instead of
4915png_uint_32.
4916
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4917Support for numbered error messages was removed by default, since we
4918never got around to actually numbering the error messages. The function
4919png_set_strip_error_numbers() was removed from the library by default.
4920
4921The png_zalloc() and png_zfree() functions are no longer exported.
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4922The png_zalloc() function no longer zeroes out the memory that it
4923allocates.
4924
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]4925Support for dithering was disabled by default in libpng-1.4.0, because
Glenn Randers-Pehrson9f1cd702011-04-16 19:40:23 -0500[diff] [blame]4926it has not been well tested and doesn't actually "dither".
4927The code was not
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]4928removed, however, and could be enabled by building libpng with
4929PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
4930was reenabled, but the function was renamed png_set_quantize() to
4931reflect more accurately what it actually does. At the same time,
4932the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4933PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
4934was renamed to PNG_READ_QUANTIZE_SUPPORTED.
Glenn Randers-Pehrson60988072010-04-13 22:11:06 -0500[diff] [blame]4935
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4936We removed the trailing '.' from the warning and error messages.
4937
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4938.SH X. Changes to Libpng from version 1.4.x to 1.5.x
4939
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4940From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4941function) incorrectly returned a value of type png_uint_32.
4942
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4943A. Changes that affect users of libpng
4944
4945There are no substantial API changes between the non-deprecated parts of
4946the 1.4.5 API and the 1.5.0 API, however the ability to directly access
4947the main libpng control structures, png_struct and png_info, deprecated
4948in earlier versions of libpng, has been completely removed from
4949libpng 1.5.
4950
Glenn Randers-Pehrson00879b12011-01-15 19:25:34 -0600[diff] [blame]4951We no longer include zlib.h in png.h. Applications that need access
4952to information in zlib.h will need to add the '#include "zlib.h"'
4953directive. It does not matter whether it is placed prior to or after
4954the '"#include png.h"' directive.
4955
4956We moved the png_strcpy(), png_strncpy(), png_strlen(), png_memcpy(),
4957png_memcmp(), png_sprintf, and png_memcpy() macros into a private
4958header file (pngpriv.h) that is not accessible to applications.
4959
Glenn Randers-Pehrson9d23b402011-01-08 10:42:01 -0600[diff] [blame]4960In png_get_iCCP, the type of "profile" was changed from png_charpp
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4961to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
Glenn Randers-Pehrson9d23b402011-01-08 10:42:01 -0600[diff] [blame]4962
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4963There are changes of form in png.h, including new and changed macros to
4964declare
Glenn Randers-Pehrsonf5ea1b72011-01-06 06:42:51 -0600[diff] [blame]4965parts of the API. Some API functions with arguments that are pointers to
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4966data not modified within the function have been corrected to declare
4967these arguments with PNG_CONST.
4968
4969Much of the internal use of C macros to control the library build has also
4970changed and some of this is visible in the exported header files, in
4971particular the use of macros to control data and API elements visible
4972during application compilation may require significant revision to
4973application code. (It is extremely rare for an application to do this.)
4974
4975Any program that compiled against libpng 1.4 and did not use deprecated
4976features or access internal library structures should compile and work
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]4977against libpng 1.5, except for the change in the prototype for
4978png_get_iCCP() and png_set_iCCP() API functions mentioned above.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4979
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]4980libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
4981interlaced images. The macros return the number of rows and columns in
4982each pass and information that can be used to de-interlace and (if
4983absolutely necessary) interlace an image.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4984
4985libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]4986the application-provided png_longjmp_ptr on the internal, but application
Glenn Randers-Pehrson33ced442011-04-27 14:58:06 -0500[diff] [blame]4987initialized, jmpbuf. It is provided as a convenience to avoid the need
4988initialized, longjmp buffer. It is provided as a convenience to avoid
4989the need to use the png_jmpbuf macro, which had the unnecessary side
4990effect of resetting the internal png_longjmp_ptr value.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4991
4992libpng 1.5.0 includes a complete fixed point API. By default this is
4993present along with the corresponding floating point API. In general the
4994fixed point API is faster and smaller than the floating point one because
4995the PNG file format used fixed point, not floating point. This applies
4996even if the library uses floating point in internal calculations. A new
4997macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
4998uses floating point arithmetic (the default) or fixed point arithmetic
4999internally for performance critical calculations such as gamma correction.
Glenn Randers-Pehrson00879b12011-01-15 19:25:34 -0600[diff] [blame]5000In some cases, the gamma calculations may produce slightly different
5001results. This has changed the results in png_rgb_to_gray and in alpha
5002composition (png_set_background for example). This applies even if the
5003original image was already linear (gamma == 1.0) and, therefore, it is
5004not necessary to linearize the image. This is because libpng has *not*
5005been changed to optimize that case correctly, yet.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5006
5007Fixed point support for the sCAL chunk comes with an important caveat;
5008the sCAL specification uses a decimal encoding of floating point values
5009and the accuracy of PNG fixed point values is insufficient for
5010representation of these values. Consequently a "string" API
5011(png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
5012arbitrary sCAL chunks in the absence of either the floating point API or
5013internal floating point calculations.
5014
5015Applications no longer need to include the optional distribution header
5016file pngusr.h or define the corresponding macros during application
5017build in order to see the correct variant of the libpng API. From 1.5.0
5018application code can check for the corresponding _SUPPORTED macro:
5019
5020#ifdef PNG_INCH_CONVERSIONS_SUPPORTED
5021 /* code that uses the inch conversion APIs. */
5022#endif
5023
5024This macro will only be defined if the inch conversion functions have been
5025compiled into libpng. The full set of macros, and whether or not support
5026has been compiled in, are available in the header file pnglibconf.h.
5027This header file is specific to the libpng build. Notice that prior to
50281.5.0 the _SUPPORTED macros would always have the default definition unless
5029reset by pngusr.h or by explicit settings on the compiler command line.
5030These settings may produce compiler warnings or errors in 1.5.0 because
5031of macro redefinition.
5032
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]5033From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5034function) incorrectly returned a value of type png_uint_32. libpng 1.5.0
5035is consistent with the implementation in 1.4.5 and 1.2.x (where the macro
5036did not exist.)
5037
5038Applications can now choose whether to use these macros or to call the
5039corresponding function by defining PNG_USE_READ_MACROS or
5040PNG_NO_USE_READ_MACROS before including png.h. Notice that this is
5041only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0
5042 will lead to a link failure.
Glenn Randers-Pehrson59fa3e92011-01-06 07:07:06 -0600[diff] [blame]5043
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]5044Prior to libpng-1.5.3, the zlib compressor used the same set of parameters
5045when compressing the IDAT data and textual data such as zTXt and iCCP.
5046In libpng-1.5.3 we reinitialized the zlib stream for each type of data.
5047We added five png_set_text_*() functions for setting the parameters to
5048use with textual data.
5049
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5050B. Changes to the build and configuration of libpng
5051
5052Details of internal changes to the library code can be found in the CHANGES
5053file. These will be of no concern to the vast majority of library users or
5054builders, however the few who configure libpng to a non-default feature
5055set may need to change how this is done.
5056
5057There should be no need for library builders to alter build scripts if
5058these use the distributed build support - configure or the makefiles -
5059however users of the makefiles may care to update their build scripts
5060to build pnglibconf.h where the corresponding makefile does not do so.
5061
5062Building libpng with a non-default configuration has changed completely.
5063The old method using pngusr.h should still work correctly even though the
5064way pngusr.h is used in the build has been changed, however library
5065builders will probably want to examine the changes to take advantage of
5066new capabilities and to simplify their build system.
5067
5068B.1 Specific changes to library configuration capabilities
5069
5070The library now supports a complete fixed point implementation and can
5071thus be used on systems which have no floating point support or very
5072limited or slow support. Previously gamma correction, an essential part
5073of complete PNG support, required reasonably fast floating point.
5074
5075As part of this the choice of internal implementation has been made
5076independent of the choice of fixed versus floating point APIs and all the
5077missing fixed point APIs have been implemented.
5078
5079The exact mechanism used to control attributes of API functions has
5080changed. A single set of operating system independent macro definitions
5081is used and operating system specific directives are defined in
5082pnglibconf.h
5083
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]5084As part of this the mechanism used to choose procedure call standards on
5085those systems that allow a choice has been changed. At present this only
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5086affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
5087running on Intel processors. As before PNGAPI is defined where required
5088to control the exported API functions; however, two new macros, PNGCBAPI
5089and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
5090(PNGCAPI) for functions that must match a C library prototype (currently
5091only png_longjmp_ptr, which must match the C longjmp function.) The new
5092approach is documented in pngconf.h
5093
5094Despite these changes libpng 1.5.0 only supports the native C function
5095calling standard on those platforms tested so far (__cdecl on Microsoft
5096Windows). This is because the support requirements for alternative
5097calling conventions seem to no longer exist. Developers who find it
5098necessary to set PNG_API_RULE to 1 should advise the mailing list
5099(png-mng-implement) of this and library builders who use Openwatcom and
5100therefore set PNG_API_RULE to 2 should also contact the mailing list.
5101
5102A new test program, pngvalid, is provided in addition to pngtest.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]5103pngvalid validates the arithmetic accuracy of the gamma correction
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5104calculations and includes a number of validations of the file format.
5105A subset of the full range of tests is run when "make check" is done
5106(in the 'configure' build.) pngvalid also allows total allocated memory
5107usage to be evaluated and performs additional memory overwrite validation.
5108
5109Many changes to individual feature macros have been made. The following
5110are the changes most likely to be noticed by library builders who
5111configure libpng:
5112
51131) All feature macros now have consistent naming:
5114
5115#define PNG_NO_feature turns the feature off
5116#define PNG_feature_SUPPORTED turns the feature on
5117
5118pnglibconf.h contains one line for each feature macro which is either:
5119
5120#define PNG_feature_SUPPORTED
5121
5122if the feature is supported or:
5123
5124/*#undef PNG_feature_SUPPORTED*/
5125
5126if it is not. Library code consistently checks for the 'SUPPORTED' macro.
5127It does not, and should not, check for the 'NO' macro which will not
5128normally be defined even if the feature is not supported.
5129
5130Compatibility with the old names is provided as follows:
5131
5132PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
5133
5134And the following definitions disable the corresponding feature:
5135
5136PNG_SETJMP_NOT_SUPPORTED disables SETJMP
5137PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
5138PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
5139PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
5140PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
5141PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
5142
5143Library builders should remove use of the above, inconsistent, names.
5144
51452) Warning and error message formatting was previously conditional on
5146the STDIO feature. The library has been changed to use the
5147CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
5148the library no longer uses the printf(3) functions, even though the
5149default read/write implementations use (FILE) style stdio.h functions.
5150
51513) Three feature macros now control the fixed/floating point decisions:
5152
5153PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
5154
5155PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
5156practice these are normally required internally anyway (because the PNG
5157file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
5158merely stops the function from being exported.
5159
5160PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
5161point implementation or the fixed point one. Typically the fixed point
5162implementation is larger and slower than the floating point implementation
5163on a system that supports floating point, however it may be faster on a
5164system which lacks floating point hardware and therefore uses a software
5165emulation.
5166
51674) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the
5168functions to read and write ints to be disabled independently of
5169PNG_USE_READ_MACROS, which allows libpng to be built with the functions
5170even though the default is to use the macros - this allows applications
5171to choose at app buildtime whether or not to use macros (previously
5172impossible because the functions weren't in the default build.)
5173
5174B.2 Changes to the configuration mechanism
5175
5176Prior to libpng-1.5.0 library builders who needed to configure libpng
5177had either to modify the exported pngconf.h header file to add system
5178specific configuration or had to write feature selection macros into
5179pngusr.h and cause this to be included into pngconf.h by defining
5180PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
5181application built without PNG_USER_CONFIG defined would see the
5182unmodified, default, libpng API and thus would probably fail to link.
5183
5184These mechanisms still work in the configure build and in any makefile
5185build that builds pnglibconf.h although the feature selection macros
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]5186have changed somewhat as described above. In 1.5.0, however, pngusr.h is
5187processed only once, when the exported header file pnglibconf.h is built.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5188pngconf.h no longer includes pngusr.h, therefore it is ignored after the
5189build of pnglibconf.h and it is never included in an application build.
5190
5191The rarely used alternative of adding a list of feature macros to the
5192CFLAGS setting in the build also still works, however the macros will be
5193copied to pnglibconf.h and this may produce macro redefinition warnings
5194when the individual C files are compiled.
5195
5196All configuration now only works if pnglibconf.h is built from
5197scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
5198(the original author of awk) maintains C source code of that awk and this
5199and all known later implementations (often called by subtly different
5200names - nawk and gawk for example) are adequate to build pnglibconf.h.
5201The Sun Microsystems (now Oracle) program 'awk' is an earlier version
5202and does not work, this may also apply to other systems that have a
5203functioning awk called 'nawk'.
5204
5205Configuration options are now documented in scripts/pnglibconf.dfa. This
5206file also includes dependency information that ensures a configuration is
5207consistent; that is, if a feature is switched off dependent features are
5208also removed. As a recommended alternative to using feature macros in
5209pngusr.h a system builder may also define equivalent options in pngusr.dfa
5210(or, indeed, any file) and add that to the configuration by setting
5211DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
5212how to do this, and a case where pngusr.h is still required.
5213
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]5214.SH XI. Detecting libpng
Glenn Randers-Pehrson424c9852009-06-02 13:45:15 -0500[diff] [blame]5215
5216The png_get_io_ptr() function has been present since libpng-0.88, has never
5217changed, and is unaffected by conditional compilation macros. It is the
5218best choice for use in configure scripts for detecting the presence of any
Glenn Randers-Pehrson99708d52009-06-29 17:30:00 -0500[diff] [blame]5219libpng version since 0.88. In an autoconf "configure.in" you could use
5220
5221 AC_CHECK_LIB(png, png_get_io_ptr, ...
Glenn Randers-Pehrson424c9852009-06-02 13:45:15 -0500[diff] [blame]5222
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]5223.SH XII. Source code repository
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5224
5225Since about February 2009, version 1.2.34, libpng has been under "git" source
5226control. The git repository was built from old libpng-x.y.z.tar.gz files
5227going back to version 0.70. You can access the git repository (read only)
5228at
5229
5230 git://libpng.git.sourceforge.net/gitroot/libpng
5231
5232or you can browse it via "gitweb" at
5233
5234 http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
5235
5236Patches can be sent to glennrp at users.sourceforge.net or to
5237png-mng-implement at lists.sourceforge.net or you can upload them to
5238the libpng bug tracker at
5239
5240 http://libpng.sourceforge.net
5241
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]5242We also accept patches built from the tar or zip distributions, and
5243simple verbal discriptions of bug fixes, reported either to the
5244SourceForge bug tracker or to the png-mng-implement at lists.sf.net
5245mailing list.
5246
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]5247.SH XIII. Coding style
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5248
5249Our coding style is similar to the "Allman" style, with curly
5250braces on separate lines:
5251
5252 if (condition)
5253 {
5254 action;
5255 }
5256
5257 else if (another condition)
5258 {
5259 another action;
5260 }
5261
5262The braces can be omitted from simple one-line actions:
5263
5264 if (condition)
5265 return (0);
5266
5267We use 3-space indentation, except for continued statements which
5268are usually indented the same as the first line of the statement
5269plus four more spaces.
5270
Glenn Randers-Pehrson5ade7ed2009-09-30 15:11:49 -0500[diff] [blame]5271For macro definitions we use 2-space indentation, always leaving the "#"
5272in the first column.
5273
5274 #ifndef PNG_NO_FEATURE
5275 # ifndef PNG_FEATURE_SUPPORTED
5276 # define PNG_FEATURE_SUPPORTED
5277 # endif
5278 #endif
5279
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5280Comments appear with the leading "/*" at the same indentation as
5281the statement that follows the comment:
5282
5283 /* Single-line comment */
5284 statement;
5285
Glenn Randers-Pehrsone4c706a2010-03-06 14:51:54 -0600[diff] [blame]5286 /* This is a multiple-line
5287 * comment.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5288 */
5289 statement;
5290
Glenn Randers-Pehrsone4c706a2010-03-06 14:51:54 -0600[diff] [blame]5291Very short comments can be placed after the end of the statement
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5292to which they pertain:
5293
5294 statement; /* comment */
5295
5296We don't use C++ style ("//") comments. We have, however,
5297used them in the past in some now-abandoned MMX assembler
5298code.
5299
Glenn Randers-Pehrsonb5444a12009-06-08 08:36:19 -0500[diff] [blame]5300Functions and their curly braces are not indented, and
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5301exported functions are marked with PNGAPI:
5302
5303 /* This is a public function that is visible to
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5304 * application programmers. It does thus-and-so.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5305 */
5306 void PNGAPI
5307 png_exported_function(png_ptr, png_info, foo)
5308 {
5309 body;
5310 }
5311
Glenn Randers-Pehrson416976f2009-07-27 22:16:09 -0500[diff] [blame]5312The prototypes for all exported functions appear in png.h,
5313above the comment that says
5314
5315 /* Maintainer: Put new public prototypes here ... */
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5316
5317We mark all non-exported functions with "/* PRIVATE */"":
5318
5319 void /* PRIVATE */
5320 png_non_exported_function(png_ptr, png_info, foo)
5321 {
5322 body;
5323 }
5324
Glenn Randers-Pehrson416976f2009-07-27 22:16:09 -0500[diff] [blame]5325The prototypes for non-exported functions (except for those in
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]5326pngtest) appear in
5327pngpriv.h
Glenn Randers-Pehrson416976f2009-07-27 22:16:09 -0500[diff] [blame]5328above the comment that says
5329
5330 /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5331
Glenn Randers-Pehrsoncbbe9a52011-01-29 16:12:11 -0600[diff] [blame]5332To avoid polluting the global namespace, the names of all exported
5333functions and variables begin with "png_", and all publicly visible C
5334preprocessor macros begin with "PNG_". We request that applications that
5335use libpng *not* begin any of their own symbols with either of these strings.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5336
5337We put a space after each comma and after each semicolon
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5338in "for" statements, and we put spaces before and after each
Glenn Randers-Pehrsone4c706a2010-03-06 14:51:54 -0600[diff] [blame]5339C binary operator and after "for" or "while", and before
5340"?". We don't put a space between a typecast and the expression
5341being cast, nor do we put one between a function name and the
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5342left parenthesis that follows it:
5343
5344 for (i = 2; i > 0; --i)
Glenn Randers-Pehrson67f3b482009-09-23 11:36:28 -0500[diff] [blame]5345 y[i] = a(x) + (int)b;
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5346
Glenn Randers-Pehrsond60c8862009-06-15 21:56:14 -0500[diff] [blame]5347We prefer #ifdef and #ifndef to #if defined() and if !defined()
5348when there is only one macro being tested.
5349
Glenn Randers-Pehrson67f3b482009-09-23 11:36:28 -0500[diff] [blame]5350We do not use the TAB character for indentation in the C sources.
5351
Glenn Randers-Pehrson62ca98e2009-12-20 15:14:57 -0600[diff] [blame]5352Lines do not exceed 80 characters.
5353
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]5354Other rules can be inferred by inspecting the libpng source.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5355
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]5356.SH XIV. Y2K Compliance in libpng
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5357
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5358June 11, 2011
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5359
5360Since the PNG Development group is an ad-hoc body, we can't make
5361an official declaration.
5362
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5363This is your unofficial assurance that libpng from version 0.71 and
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5364upward through 1.5.3beta11 are Y2K compliant. It is my belief that earlier
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5365versions were also Y2K compliant.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5366
5367Libpng only has three year fields. One is a 2-byte unsigned integer that
5368will hold years up to 65535. The other two hold the date in text
5369format, and will hold years up to 9999.
5370
5371The integer is
5372 "png_uint_16 year" in png_time_struct.
5373
5374The strings are
5375 "png_charp time_buffer" in png_struct and
5376 "near_time_buffer", which is a local character string in png.c.
5377
5378There are seven time-related functions:
5379
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5380 png_convert_to_rfc_1123() in png.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5381 (formerly png_convert_to_rfc_1152() in error)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5382 png_convert_from_struct_tm() in pngwrite.c, called
5383 in pngwrite.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5384 png_convert_from_time_t() in pngwrite.c
5385 png_get_tIME() in pngget.c
5386 png_handle_tIME() in pngrutil.c, called in pngread.c
5387 png_set_tIME() in pngset.c
5388 png_write_tIME() in pngwutil.c, called in pngwrite.c
5389
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5390All appear to handle dates properly in a Y2K environment. The
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5391png_convert_from_time_t() function calls gmtime() to convert from system
5392clock time, which returns (year - 1900), which we properly convert to
5393the full 4-digit year. There is a possibility that applications using
5394libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5395function, or that they are incorrectly passing only a 2-digit year
5396instead of "year - 1900" into the png_convert_from_struct_tm() function,
5397but this is not under our control. The libpng documentation has always
5398stated that it works with 4-digit years, and the APIs have been
5399documented as such.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5400
5401The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
5402integer to hold the year, and can hold years as large as 65535.
5403
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5404zlib, upon which libpng depends, is also Y2K compliant. It contains
5405no date-related code.
5406
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5407
5408 Glenn Randers-Pehrson
5409 libpng maintainer
5410 PNG Development Group
5411
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5412.SH NOTE
5413
5414Note about libpng version numbers:
5415
5416Due to various miscommunications, unforeseen code incompatibilities
5417and occasional factors outside the authors' control, version numbering
5418on the library has not always been consistent and straightforward.
5419The following table summarizes matters since version 0.89c, which was
5420the first widely used release:
5421
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5422 source png.h png.h shared-lib
5423 version string int version
5424 ------- ------ ----- ----------
5425 0.89c ("beta 3") 0.89 89 1.0.89
5426 0.90 ("beta 4") 0.90 90 0.90
5427 0.95 ("beta 5") 0.95 95 0.95
5428 0.96 ("beta 6") 0.96 96 0.96
5429 0.97b ("beta 7") 1.00.97 97 1.0.1
5430 0.97c 0.97 97 2.0.97
5431 0.98 0.98 98 2.0.98
5432 0.99 0.99 98 2.0.99
5433 0.99a-m 0.99 99 2.0.99
5434 1.00 1.00 100 2.1.0
5435 1.0.0 1.0.0 100 2.1.0
5436 1.0.0 (from here on, the 100 2.1.0
5437 1.0.1 png.h string is 10001 2.1.0
5438 1.0.1a-e identical to the 10002 from here on, the
5439 1.0.2 source version) 10002 shared library is 2.V
5440 1.0.2a-b 10003 where V is the source
5441 1.0.1 10001 code version except as
5442 1.0.1a-e 10002 2.1.0.1a-e noted.
5443 1.0.2 10002 2.1.0.2
5444 1.0.2a-b 10003 2.1.0.2a-b
5445 1.0.3 10003 2.1.0.3
5446 1.0.3a-d 10004 2.1.0.3a-d
5447 1.0.4 10004 2.1.0.4
5448 1.0.4a-f 10005 2.1.0.4a-f
5449 1.0.5 (+ 2 patches) 10005 2.1.0.5
5450 1.0.5a-d 10006 2.1.0.5a-d
5451 1.0.5e-r 10100 2.1.0.5e-r
5452 1.0.5s-v 10006 2.1.0.5s-v
5453 1.0.6 (+ 3 patches) 10006 2.1.0.6
5454 1.0.6d-g 10007 2.1.0.6d-g
5455 1.0.6h 10007 10.6h
5456 1.0.6i 10007 10.6i
5457 1.0.6j 10007 2.1.0.6j
Glenn Randers-Pehrson25467032011-01-28 11:58:40 -0600[diff] [blame]5458 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5459 1.0.7beta15-18 1 10007 2.1.0.7beta15-18
5460 1.0.7rc1-2 1 10007 2.1.0.7rc1-2
5461 1.0.7 1 10007 2.1.0.7
5462 1.0.8beta1-4 1 10008 2.1.0.8beta1-4
5463 1.0.8rc1 1 10008 2.1.0.8rc1
5464 1.0.8 1 10008 2.1.0.8
5465 1.0.9beta1-6 1 10009 2.1.0.9beta1-6
5466 1.0.9rc1 1 10009 2.1.0.9rc1
5467 1.0.9beta7-10 1 10009 2.1.0.9beta7-10
5468 1.0.9rc2 1 10009 2.1.0.9rc2
5469 1.0.9 1 10009 2.1.0.9
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]5470 1.0.10beta1 1 10010 2.1.0.10beta1
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5471 1.0.10rc1 1 10010 2.1.0.10rc1
Glenn Randers-Pehrson13cfbac2001-03-30 06:42:28 -0600[diff] [blame]5472 1.0.10 1 10010 2.1.0.10
Glenn Randers-Pehrsone1eff582001-04-14 20:15:41 -0500[diff] [blame]5473 1.0.11beta1-3 1 10011 2.1.0.11beta1-3
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]5474 1.0.11rc1 1 10011 2.1.0.11rc1
Glenn Randers-Pehrson32835392001-04-27 08:29:32 -0500[diff] [blame]5475 1.0.11 1 10011 2.1.0.11
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]5476 1.0.12beta1-2 2 10012 2.1.0.12beta1-2
5477 1.0.12rc1 2 10012 2.1.0.12rc1
5478 1.0.12 2 10012 2.1.0.12
5479 1.1.0a-f - 10100 2.1.1.0a-f abandoned
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]5480 1.2.0beta1-2 2 10200 2.1.2.0beta1-2
Glenn Randers-Pehrson5a0be342001-10-18 20:55:13 -0500[diff] [blame]5481 1.2.0beta3-5 3 10200 3.1.2.0beta3-5
5482 1.2.0rc1 3 10200 3.1.2.0rc1
5483 1.2.0 3 10200 3.1.2.0
Glenn Randers-Pehrson5cded0b2001-11-07 07:10:08 -0600[diff] [blame]5484 1.2.1beta-4 3 10201 3.1.2.1beta1-4
Glenn Randers-Pehrsondb3b88d2001-12-04 06:30:43 -0600[diff] [blame]5485 1.2.1rc1-2 3 10201 3.1.2.1rc1-2
5486 1.2.1 3 10201 3.1.2.1
Glenn Randers-Pehrson25228ab2002-03-31 07:33:55 -0600[diff] [blame]5487 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6
Glenn Randers-Pehrsonfcbd7872002-04-07 16:35:38 -0500[diff] [blame]5488 1.0.13beta1 10 10013 10.so.0.1.0.13beta1
5489 1.0.13rc1 10 10013 10.so.0.1.0.13rc1
5490 1.2.2rc1 12 10202 12.so.0.1.2.2rc1
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]5491 1.0.13 10 10013 10.so.0.1.0.13
5492 1.2.2 12 10202 12.so.0.1.2.2
Glenn Randers-Pehrson22f28962002-05-13 18:17:09 -0500[diff] [blame]5493 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6
5494 1.2.3 12 10203 12.so.0.1.2.3
Glenn Randers-Pehrsond020e9d2002-06-28 09:34:00 -0500[diff] [blame]5495 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3
Glenn Randers-Pehrson2ae022d2002-07-01 22:23:46 -0500[diff] [blame]5496 1.2.4rc1 13 10204 12.so.0.1.2.4rc1
Glenn Randers-Pehrson484a8a12002-07-07 19:15:20 -0500[diff] [blame]5497 1.0.14 10 10014 10.so.0.1.0.14
5498 1.2.4 13 10204 12.so.0.1.2.4
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]5499 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
5500 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5501 1.0.15 10 10015 10.so.0.1.0.15
5502 1.2.5 13 10205 12.so.0.1.2.5
5503 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
Glenn Randers-Pehrson37f116a2004-08-15 07:15:39 -0500[diff] [blame]5504 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
5505 1.0.16 10 10016 10.so.0.1.0.16
5506 1.2.6 13 10206 12.so.0.1.2.6
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]5507 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]5508 1.0.17rc1 10 10017 12.so.0.1.0.17rc1
5509 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
Glenn Randers-Pehrson250dfe12004-09-11 21:19:54 -0500[diff] [blame]5510 1.0.17 10 10017 12.so.0.1.0.17
5511 1.2.7 13 10207 12.so.0.1.2.7
Glenn Randers-Pehrson40936072004-11-20 11:18:40 -0600[diff] [blame]5512 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
Glenn Randers-Pehrson584b96e2004-11-29 15:08:00 -0600[diff] [blame]5513 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5
5514 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
Glenn Randers-Pehrson917648e2004-12-02 18:14:51 -0600[diff] [blame]5515 1.0.18 10 10018 12.so.0.1.0.18
5516 1.2.8 13 10208 12.so.0.1.2.8
Glenn Randers-Pehrsone6474622006-03-04 16:50:47 -0600[diff] [blame]5517 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
Glenn Randers-Pehrson4deeb792006-03-22 16:21:59 -0600[diff] [blame]5518 1.2.9beta4-11 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrson3a512032006-03-31 05:29:33 -0600[diff] [blame]5519 1.2.9rc1 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsona7d0c942006-04-14 06:22:52 -0500[diff] [blame]5520 1.2.9 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]5521 1.2.10beta1-7 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson17218292006-04-20 07:20:46 -0500[diff] [blame]5522 1.2.10rc1-2 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson86dc9812006-05-10 07:27:44 -0500[diff] [blame]5523 1.2.10 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]5524 1.4.0beta1-6 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrsond60c8862009-06-15 21:56:14 -0500[diff] [blame]5525 1.2.11beta1-4 13 10210 12.so.0.11[.0]
Glenn Randers-Pehrson3424ee72006-07-12 13:33:47 -0500[diff] [blame]5526 1.4.0beta7-8 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrson701dbaa2006-11-17 09:36:54 -0600[diff] [blame]5527 1.2.11 13 10211 12.so.0.11[.0]
5528 1.2.12 13 10212 12.so.0.12[.0]
5529 1.4.0beta9-14 14 10400 14.so.0.0[.0]
5530 1.2.13 13 10213 12.so.0.13[.0]
Glenn Randers-Pehrson97a9b482008-10-25 20:03:28 -0500[diff] [blame]5531 1.4.0beta15-36 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrsonfa028102009-10-10 06:15:21 -0500[diff] [blame]5532 1.4.0beta37-87 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrson733da8c2009-10-30 00:00:15 -0500[diff] [blame]5533 1.4.0rc01 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrson62ca98e2009-12-20 15:14:57 -0600[diff] [blame]5534 1.4.0beta88-109 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrson67a83db2010-01-01 18:26:18 -0600[diff] [blame]5535 1.4.0rc02-08 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrsondbcfb712009-12-25 14:24:18 -0600[diff] [blame]5536 1.4.0 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]5537 1.4.1beta01-03 14 10401 14.so.14.1[.0]
5538 1.4.1rc01 14 10401 14.so.14.1[.0]
Glenn Randers-Pehrson7a5be532010-02-14 07:16:19 -0600[diff] [blame]5539 1.4.1beta04-12 14 10401 14.so.14.1[.0]
Glenn Randers-Pehrsonaaf377c2010-03-08 11:20:30 -0600[diff] [blame]5540 1.4.1 14 10401 14.so.14.1[.0]
Glenn Randers-Pehrson5b3d5542010-06-18 21:55:53 -0500[diff] [blame]5541 1.4.2 14 10402 14.so.14.2[.0]
5542 1.4.3 14 10403 14.so.14.3[.0]
Glenn Randers-Pehrson2776d5e2010-11-21 15:18:02 -0600[diff] [blame]5543 1.4.4 14 10404 14.so.14.4[.0]
Glenn Randers-Pehrsonfd20a5a2010-12-27 08:53:08 -0600[diff] [blame]5544 1.5.0beta01-58 15 10500 15.so.15.0[.0]
Glenn Randers-Pehrson64b863c2011-01-04 09:57:06 -0600[diff] [blame]5545 1.5.0rc01-07 15 10500 15.so.15.0[.0]
Glenn Randers-Pehrsonf5ea1b72011-01-06 06:42:51 -0600[diff] [blame]5546 1.5.0 15 10500 15.so.15.0[.0]
Glenn Randers-Pehrsonef123cc2011-01-28 15:20:34 -0600[diff] [blame]5547 1.5.1beta01-11 15 10501 15.so.15.1[.0]
Glenn Randers-Pehrson3d3aae12011-02-02 22:58:27 -0600[diff] [blame]5548 1.5.1rc01-02 15 10501 15.so.15.1[.0]
5549 1.5.1 15 10501 15.so.15.1[.0]
Glenn Randers-Pehrsonf3dd1cc2011-03-18 22:02:20 -0500[diff] [blame]5550 1.5.2beta01-03 15 10502 15.so.15.2[.0]
Glenn Randers-Pehrson77fd0832011-03-24 08:59:48 -0500[diff] [blame]5551 1.5.2rc01-03 15 10502 15.so.15.2[.0]
Glenn Randers-Pehrsondcc35052011-03-31 11:23:49 -0500[diff] [blame]5552 1.5.2 15 10502 15.so.15.2[.0]
Glenn Randers-Pehrson36edbb52011-06-03 07:15:04 -0500[diff] [blame]5553 1.5.3beta01-10 15 10503 15.so.15.3[.0]
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5554 1.5.3rc01-02 15 10503 15.so.15.3[.0]
5555 1.5.3beta11 15 10503 15.so.15.3[.0]
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5556
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5557Henceforth the source version will match the shared-library minor
5558and patch numbers; the shared-library major version number will be
5559used for changes in backward compatibility, as it is intended. The
5560PNG_PNGLIB_VER macro, which is not used within libpng but is available
5561for applications, is an unsigned integer of the form xyyzz corresponding
5562to the source version x.y.z (leading zeros in y and z). Beta versions
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]5563were given the previous public release number plus a letter, until
5564version 1.0.6j; from then on they were given the upcoming public
5565release number plus "betaNN" or "rcN".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5566
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5567.SH "SEE ALSO"
Glenn Randers-Pehrson4e763f12010-03-03 10:45:50 -0600[diff] [blame]5568.BR "png"(5), " libpngpf"(3), " zlib"(3), " deflate"(5), " " and " zlib"(5)
Glenn Randers-Pehrson7fb32a82010-03-03 09:47:49 -0600[diff] [blame]5569
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5570.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5571.IR libpng :
5572.IP
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]5573http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]5574http://www.libpng.org/pub/png
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5575
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5576.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5577.IR zlib :
5578.IP
5579(generally) at the same location as
5580.I libpng
5581or at
5582.br
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]5583ftp://ftp.info-zip.org/pub/infozip/zlib
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5584
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5585.LP
5586.IR PNG specification: RFC 2083
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5587.IP
5588(generally) at the same location as
5589.I libpng
5590or at
5591.br
5592ftp://ds.internic.net/rfc/rfc2083.txt
5593.br
5594or (as a W3C Recommendation) at
5595.br
5596http://www.w3.org/TR/REC-png.html
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5597
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5598.LP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5599In the case of any inconsistency between the PNG specification
5600and this library, the specification takes precedence.
5601
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5602.SH AUTHORS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5603This man page: Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]5604<glennrp at users.sourceforge.net>
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5605
5606The contributing authors would like to thank all those who helped
5607with testing, bug fixes, and patience. This wouldn't have been
5608possible without all of you.
5609
5610Thanks to Frank J. T. Wojcik for helping with the documentation.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5611
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5612Libpng version 1.5.3beta11 - June 11, 2011:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5613Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]5614Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5615
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5616Supported by the PNG development group
5617.br
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]5618png-mng-implement at lists.sf.net
5619(subscription required; visit
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]5620png-mng-implement at lists.sourceforge.net (subscription required; visit
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]5621https://lists.sourceforge.net/lists/listinfo/png-mng-implement
5622to subscribe).
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5623
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5624.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5625
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]5626(This copy of the libpng notices is provided for your convenience. In case of
5627any discrepancy between this copy and the notices in the file png.h that is
5628included in the libpng distribution, the latter shall prevail.)
5629
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5630If you modify libpng you may insert additional notices immediately following
5631this sentence.
5632
Glenn Randers-Pehrsonbfbf8652009-06-26 21:46:52 -0500[diff] [blame]5633This code is released under the libpng license.
Glenn Randers-Pehrson037023b2009-06-24 10:27:36 -0500[diff] [blame]5634
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5635libpng versions 1.2.6, August 15, 2004, through 1.5.3beta11, June 11, 2011, are
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame]5636Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5637distributed according to the same disclaimer and license as libpng-1.2.5
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]5638with the following individual added to the list of Contributing Authors
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5639
5640 Cosmin Truta
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5641
5642libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are
Glenn Randers-Pehrsonc6de22d2002-02-23 18:55:25 -0600[diff] [blame]5643Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson32fc5ce2000-07-24 06:34:14 -0500[diff] [blame]5644distributed according to the same disclaimer and license as libpng-1.0.6
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5645with the following individuals added to the list of Contributing Authors
5646
5647 Simon-Pierre Cadieux
5648 Eric S. Raymond
5649 Gilles Vollant
5650
5651and with the following additions to the disclaimer:
5652
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5653 There is no warranty against interference with your
5654 enjoyment of the library or against infringement.
5655 There is no warranty that our efforts or the library
5656 will fulfill any of your particular purposes or needs.
5657 This library is provided with all faults, and the entire
5658 risk of satisfactory quality, performance, accuracy, and
5659 effort is with the user.
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5660
5661libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
5662Copyright (c) 1998, 1999 Glenn Randers-Pehrson
5663Distributed according to the same disclaimer and license as libpng-0.96,
5664with the following individuals added to the list of Contributing Authors:
5665
5666 Tom Lane
5667 Glenn Randers-Pehrson
5668 Willem van Schaik
5669
5670libpng versions 0.89, June 1996, through 0.96, May 1997, are
Glenn Randers-Pehrson54a066a1999-09-19 06:04:18 -0500[diff] [blame]5671Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5672Distributed according to the same disclaimer and license as libpng-0.88,
5673with the following individuals added to the list of Contributing Authors:
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5674
5675 John Bowler
5676 Kevin Bracey
5677 Sam Bushell
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5678 Magnus Holmgren
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5679 Greg Roelofs
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5680 Tom Tanner
5681
5682libpng versions 0.5, May 1995, through 0.88, January 1996, are
5683Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
5684
5685For the purposes of this copyright and license, "Contributing Authors"
5686is defined as the following set of individuals:
5687
5688 Andreas Dilger
5689 Dave Martindale
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5690 Guy Eric Schalnat
5691 Paul Schmidt
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5692 Tim Wegner
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]5693
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5694The PNG Reference Library is supplied "AS IS". The Contributing Authors
5695and Group 42, Inc. disclaim all warranties, expressed or implied,
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5696including, without limitation, the warranties of merchantability and of
5697fitness for any purpose. The Contributing Authors and Group 42, Inc.
5698assume no liability for direct, indirect, incidental, special, exemplary,
5699or consequential damages, which may result from the use of the PNG
5700Reference Library, even if advised of the possibility of such damage.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5701
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5702Permission is hereby granted to use, copy, modify, and distribute this
5703source code, or portions hereof, for any purpose, without fee, subject
5704to the following restrictions:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5705
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]57061. The origin of this source code must not be misrepresented.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5707
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]57082. Altered versions must be plainly marked as such and
5709 must not be misrepresented as being the original source.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5710
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]57113. This Copyright notice may not be removed or altered from
5712 any source or altered source distribution.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5713
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5714The Contributing Authors and Group 42, Inc. specifically permit, without
5715fee, and encourage the use of this source code as a component to
5716supporting the PNG file format in commercial products. If you use this
5717source code in a product, acknowledgment is not required but would be
5718appreciated.
5719
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5720
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5721A "png_get_copyright" function is available, for convenient use in "about"
5722boxes and the like:
5723
5724 printf("%s",png_get_copyright(NULL));
5725
5726Also, the PNG logo (in PNG format, of course) is supplied in the
Glenn Randers-Pehrsona4d54bd2000-07-14 08:15:12 -0500[diff] [blame]5727files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5728
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5729Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5730certification mark of the Open Source Initiative.
5731
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5732Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]5733glennrp at users.sourceforge.net
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5734June 11, 2011
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5735
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5736.\" end of man page
5737