libpng.3@ 67439

Last change on this file since 67439 was 58796, checked in by vboxsync, 9 years ago
libpng 1.2.54 unmodified
Property svn:eol-style set to `native`
File size: 164.5 KB

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

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/libpng-1.2.54/libpng.3@ 67439

Download in other formats: