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