src/png/libpng.3

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