core/libs/libpng-1.2.18/libpng.3

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