1 .TH LIBPNG 3 "January 31, 2001"
3 libpng \- Portable Network Graphics (PNG) Reference Library 1.0.9
11 \fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP
15 \fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\fP\fB);\fP
19 \fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
23 \fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
27 \fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP
31 \fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP
35 \fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP
39 \fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP
43 \fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
47 \fBpng_structp png_create_read_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
51 \fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
55 \fBpng_structp png_create_write_struct_2(png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
59 \fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP
63 \fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP
67 \fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\fP\fB);\fP
71 \fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
75 \fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP
79 \fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
83 \fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
87 \fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
91 \fBvoid png_free_chunk_list (png_structp \fIpng_ptr\fP\fB);\fP
95 \fBvoid png_free_default(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
99 \fBvoid png_free_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\fP\fB);\fP
103 \fBpng_byte png_get_bit_depth (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
107 \fBpng_uint_32 png_get_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
111 \fBpng_byte png_get_channels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
115 \fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
119 \fBpng_uint_32 png_get_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
123 \fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
127 \fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
131 \fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP
135 \fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP
139 \fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
143 \fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
147 \fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
151 \fBpng_byte png_get_header_ver (png_structp \fIpng_ptr\fP\fB);\fP
155 \fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP
159 \fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
163 \fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
167 \fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP
171 \fBpng_uint_32 png_get_image_height (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
175 \fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
179 \fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
183 \fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP
187 \fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP
191 \fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP
195 \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
199 \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
203 \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
207 \fBfloat png_get_pixel_aspect_ratio (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
211 \fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
215 \fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP
219 \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
223 \fBpng_byte png_get_rgb_to_gray_status (png_structp \fIpng_ptr)
225 \fBpng_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
229 \fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
233 \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
237 \fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
241 \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
245 \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
249 \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
253 \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
257 \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
261 \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
265 \fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP
269 \fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP
273 \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
277 \fBpng_int_32 png_get_x_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
281 \fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
285 \fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
289 \fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
293 \fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
297 \fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
301 \fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
305 \fBvoid png_info_init (png_infop \fIinfo_ptr\fP\fB);\fP
309 \fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP
313 \fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
317 \fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
321 \fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP
325 \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
329 \fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP
333 \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
337 \fBvoid png_permit_empty_plte (png_structp \fP\fIpng_ptr\fP\fB, int \fIempty_plte_permitted\fP\fB);\fP
341 \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
345 \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
349 \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
353 \fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
357 \fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
361 \fBDEPRECATED: void png_read_init (png_structp \fIpng_ptr\fP\fB);\fP
365 \fBDEPRECATED: void png_read_init_2 (png_structp \fP\fIpng_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
367 \fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
371 \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
375 \fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
379 \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
383 \fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
387 \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
391 \fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP
395 \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
399 \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
403 \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
407 \fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
411 \fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
415 \fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP
419 \fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
423 \fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
427 \fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP
431 \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
435 \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
439 \fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
443 \fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
447 \fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP
451 \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
455 \fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP
459 \fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP
463 \fBvoid png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP
467 \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
471 \fBvoid png_set_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP
475 \fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
479 \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
483 \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
487 \fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP
491 \fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP
495 \fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP
499 \fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP
503 \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
507 \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
511 \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
515 \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
519 \fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP
523 \fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP
527 \fBvoid png_set_palette_to_rgb(png_structp \fIpng_ptr\fP\fB);\fP
531 \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
535 \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
539 \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
543 \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
547 \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
551 \fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP
555 \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
559 \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
563 \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
567 \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
571 \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
575 \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
579 \fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP
583 \fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP
587 \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
591 \fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP
595 \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
599 \fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP
603 \fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP
607 \fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP
611 \fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP
615 \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
619 \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
623 \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
627 \fBvoid png_set_tRNS_to_alpha(png_structp \fIpng_ptr\fP\fB);\fP
631 \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
635 \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
639 \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
643 \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
647 \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
651 \fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP
655 \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
659 \fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
663 \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
667 \fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP
671 \fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
675 \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
679 \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
683 \fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP
687 \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
691 \fBvoid png_write_destroy (png_structp \fIpng_ptr\fP\fB);\fP
695 \fBvoid png_write_destroy_info (png_infop \fIinfo_ptr\fP\fB);\fP
699 \fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
703 \fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP
707 \fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
711 \fBDEPRECATED: void png_write_init (png_structp \fIpng_ptr\fP\fB);\fP
715 \fBDEPRECATED: void png_write_init_2 (png_structp \fP\fIpng_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
719 \fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
723 \fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
727 \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
731 \fBvoid png_write_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIrow\fP\fB);\fP
735 \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
742 library supports encoding, decoding, and various manipulations of
743 the Portable Network Graphics (PNG) format image files. It uses the
746 Following is a copy of the libpng.txt file that accompanies libpng.
748 libpng.txt - A description on how to use and modify libpng
750 libpng version 1.0.9 - January 31, 2001
751 Updated and distributed by Glenn Randers-Pehrson
752 <randeg@alum.rpi.edu>
753 Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson
754 For conditions of distribution and use, see copyright
759 libpng 1.0 beta 6 version 0.96 May 28, 1997
760 Updated and distributed by Andreas Dilger
761 Copyright (c) 1996, 1997 Andreas Dilger
763 libpng 1.0 beta 2 - version 0.88 January 26, 1996
764 For conditions of distribution and use, see copyright
765 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
766 Schalnat, Group 42, Inc.
768 Updated/rewritten per request in the libpng FAQ
769 Copyright (c) 1995, 1996 Frank J. T. Wojcik
770 December 18, 1995 & January 20, 1996
774 This file describes how to use and modify the PNG reference library
775 (known as libpng) for your own use. There are five sections to this
776 file: introduction, structures, reading, writing, and modification and
777 configuration notes for various special platforms. In addition to this
778 file, example.c is a good starting point for using the library, as
779 it is heavily commented and should include everything most people
780 will need. We assume that libpng is already installed; see the
781 INSTALL file for instructions on how to install libpng.
783 Libpng was written as a companion to the PNG specification, as a way
784 of reducing the amount of time and effort it takes to support the PNG
785 file format in application programs.
787 The PNG-1.2 specification is available at <http://www.libpng.org/pub/png>
788 and at <ftp://ftp.uu.net/graphics/png/documents/>.
790 The PNG-1.0 specification is available
791 as RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as a
792 W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
793 additional chunks are described in the special-purpose public chunks
794 documents at <ftp://ftp.uu.net/graphics/png/documents/>.
797 about PNG, and the latest version of libpng, can be found at the PNG home
798 page, <http://www.libpng.org/pub/png/>
799 and at <ftp://ftp.uu.net/graphics/png/>.
801 Most users will not have to modify the library significantly; advanced
802 users may want to modify it more. All attempts were made to make it as
803 complete as possible, while keeping the code easy to understand.
804 Currently, this library only supports C. Support for other languages
807 Libpng has been designed to handle multiple sessions at one time,
808 to be easily modifiable, to be portable to the vast majority of
809 machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
810 to use. The ultimate goal of libpng is to promote the acceptance of
811 the PNG file format in whatever way possible. While there is still
812 work to be done (see the TODO file), libpng should cover the
813 majority of the needs of its users.
815 Libpng uses zlib for its compression and decompression of PNG files.
816 Further information about zlib, and the latest version of zlib, can
817 be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
818 The zlib compression utility is a general purpose utility that is
819 useful for more than PNG files, and can be used without libpng.
820 See the documentation delivered with zlib for more details.
821 You can usually find the source files for the zlib utility wherever you
822 find the libpng source files.
824 Libpng is thread safe, provided the threads are using different
825 instances of the structures. Each thread should have its own
826 png_struct and png_info instances, and thus its own image.
827 Libpng does not protect itself against two threads using the
828 same instance of a structure.
833 There are two main structures that are important to libpng, png_struct
834 and png_info. The first, png_struct, is an internal structure that
835 will not, for the most part, be used by a user except as the first
836 variable passed to every libpng function call.
838 The png_info structure is designed to provide information about the
839 PNG file. At one time, the fields of png_info were intended to be
840 directly accessible to the user. However, this tended to cause problems
841 with applications using dynamically loaded libraries, and as a result
842 a set of interface functions for png_info (the png_get_*() and png_set_*()
843 functions) was developed. The fields of png_info are still available for
844 older applications, but it is suggested that applications use the new
845 interfaces if at all possible.
847 Applications that do make direct access to the members of png_struct (except
848 for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
849 and applications that make direct access to the members of png_info must
850 be recompiled if they were compiled or loaded with libpng version 1.0.6,
851 in which the members were in a different order. In version 1.0.7, the
852 members of the png_info structure reverted to the old order, as they were
853 in versions 0.97c through 1.0.5. Starting with version 2.0.0, both
854 structures are going to be hidden, and the contents of the structures will
855 only be accessible through the png_get/png_set functions.
857 The png.h header file is an invaluable reference for programming with libpng.
858 And while I'm on the topic, make sure you include the libpng header file:
864 We'll now walk you through the possible functions to call when reading
865 in a PNG file sequentially, briefly explaining the syntax and purpose
866 of each one. See example.c and png.h for more detail. While
867 progressive reading is covered in the next section, you will still
868 need some of the functions discussed in this section to read a PNG
873 You will want to do the I/O initialization(*) before you get into libpng,
874 so if it doesn't work, you don't have much to undo. Of course, you
875 will also want to insure that you are, in fact, dealing with a PNG
876 file. Libpng provides a simple check to see if a file is a PNG file.
877 To use it, pass in the first 1 to 8 bytes of the file to the function
878 png_sig_cmp(), and it will return 0 if the bytes match the corresponding
879 bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes
880 you pass in, the greater the accuracy of the prediction.
882 If you are intending to keep the file pointer open for use in libpng,
883 you must ensure you don't read more than 8 bytes from the beginning
884 of the file, and you also have to make a call to png_set_sig_bytes_read()
885 with the number of bytes you read from the beginning. Libpng will
886 then only check the bytes (if any) that your program didn't read.
888 (*): If you are not using the standard I/O functions, you will need
889 to replace them with custom functions. See the discussion under
893 FILE *fp = fopen(file_name, "rb");
898 fread(header, 1, number, fp);
899 is_png = !png_sig_cmp(header, 0, number);
906 Next, png_struct and png_info need to be allocated and initialized. In
907 order to ensure that the size of these structures is correct even with a
908 dynamically linked libpng, there are functions to initialize and
909 allocate the structures. We also pass the library version, optional
910 pointers to error handling functions, and a pointer to a data struct for
911 use by the error functions, if necessary (the pointer and functions can
912 be NULL if the default error handlers are to be used). See the section
913 on Changes to Libpng below regarding the old initialization functions.
914 The structure allocation functions quietly return NULL if they fail to
915 create the structure, so your application should check for that.
917 png_structp png_ptr = png_create_read_struct
918 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
919 user_error_fn, user_warning_fn);
923 png_infop info_ptr = png_create_info_struct(png_ptr);
926 png_destroy_read_struct(&png_ptr,
927 (png_infopp)NULL, (png_infopp)NULL);
931 png_infop end_info = png_create_info_struct(png_ptr);
934 png_destroy_read_struct(&png_ptr, &info_ptr,
939 If you want to use your own memory allocation routines,
940 define PNG_USER_MEM_SUPPORTED and use
941 png_create_read_struct_2() instead of png_create_read_struct():
943 png_structp png_ptr = png_create_read_struct_2
944 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
945 user_error_fn, user_warning_fn, (png_voidp)
946 user_mem_ptr, user_malloc_fn, user_free_fn);
948 The error handling routines passed to png_create_read_struct()
949 and the memory alloc/free routines passed to png_create_struct_2()
950 are only necessary if you are not using the libpng supplied error
951 handling and memory alloc/free functions.
953 When libpng encounters an error, it expects to longjmp back
954 to your routine. Therefore, you will need to call setjmp and pass
955 your png_jmpbuf(png_ptr). If you read the file from different
956 routines, you will need to update the jmpbuf field every time you enter
957 a new routine that will call a png_*() function.
959 See your documentation of setjmp/longjmp for your compiler for more
960 information on setjmp/longjmp. See the discussion on libpng error
961 handling in the Customizing Libpng section below for more information
962 on the libpng error handling. If an error occurs, and libpng longjmp's
963 back to your setjmp, you will want to call png_destroy_read_struct() to
966 if (setjmp(png_jmpbuf(png_ptr)))
968 png_destroy_read_struct(&png_ptr, &info_ptr,
974 If you would rather avoid the complexity of setjmp/longjmp issues,
975 you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
976 errors will result in a call to PNG_ABORT() which defaults to abort().
978 Now you need to set up the input code. The default for libpng is to
979 use the C function fread(). If you use this, you will need to pass a
980 valid FILE * in the function png_init_io(). Be sure that the file is
981 opened in binary mode. If you wish to handle reading data in another
982 way, you need not call the png_init_io() function, but you must then
983 implement the libpng I/O methods discussed in the Customizing Libpng
986 png_init_io(png_ptr, fp);
988 If you had previously opened the file and read any of the signature from
989 the beginning in order to see if this was a PNG file, you need to let
990 libpng know that there are some bytes missing from the start of the file.
992 png_set_sig_bytes(png_ptr, number);
994 .SS Setting up callback code
996 You can set up a callback function to handle any unknown chunks in the
997 input stream. You must supply the function
999 read_chunk_callback(png_ptr ptr,
1000 png_unknown_chunkp chunk);
1002 /* The unknown chunk structure contains your
1007 /* Note that libpng has already taken care of the
1010 /* put your code here. Return one of the following: */
1012 return (-n); /* chunk had an error */
1013 return (0); /* did not recognize */
1014 return (n); /* success */
1017 (You can give your function another name that you like instead of
1018 "read_chunk_callback")
1020 To inform libpng about your function, use
1022 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1023 read_chunk_callback);
1025 This names not only the callback function, but also a user pointer that
1026 you can retrieve with
1028 png_get_user_chunk_ptr(png_ptr);
1030 At this point, you can set up a callback function that will be
1031 called after each row has been read, which you can use to control
1032 a progress meter or the like. It's demonstrated in pngtest.c.
1033 You must supply a function
1035 void read_row_callback(png_ptr ptr, png_uint_32 row, int pass);
1037 /* put your code here */
1040 (You can give it another name that you like instead of "read_row_callback")
1042 To inform libpng about your function, use
1044 png_set_read_status_fn(png_ptr, read_row_callback);
1046 .SS Unknown-chunk handling
1048 Now you get to set the way the library processes unknown chunks in the
1049 input PNG stream. Both known and unknown chunks will be read. Normal
1050 behavior is that known chunks will be parsed into information in
1051 various info_ptr members; unknown chunks will be discarded. To change
1054 png_set_keep_unknown_chunks(png_ptr, info_ptr, keep,
1055 chunk_list, num_chunks);
1056 keep - 0: do not keep
1057 1: keep only if safe-to-copy
1058 2: keep even if unsafe-to-copy
1059 chunk_list - list of chunks affected (a byte string,
1060 five bytes per chunk, NULL or '\0' if
1062 num_chunks - number of chunks affected; if 0, all
1063 unknown chunks are affected
1065 Unknown chunks declared in this way will be saved as raw data onto a
1066 list of png_unknown_chunk structures. If a chunk that is normally
1067 known to libpng is named in the list, it will be handled as unknown,
1068 according to the "keep" directive. If a chunk is named in successive
1069 instances of png_set_keep_unknown_chunks(), the final instance will
1072 .SS The high-level read interface
1074 At this point there are two ways to proceed; through the high-level
1075 read interface, or through a sequence of low-level read operations.
1076 You can use the high-level interface if (a) you are willing to read
1077 the entire image into memory, and (b) the input transformations
1078 you want to do are limited to the following set:
1080 PNG_TRANSFORM_IDENTITY No transformation
1081 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to 8 bits
1082 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
1083 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit samples to bytes
1084 PNG_TRANSFORM_PACKSWAP Change order of packed pixels to LSB first
1085 PNG_TRANSFORM_EXPAND Perform set_expand()
1086 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
1087 PNG_TRANSFORM_SHIFT Normalize pixels to the sBIT depth
1088 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA to BGRA
1089 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA to AG
1090 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity to transparency
1091 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
1093 (This excludes setting a background color, doing gamma transformation,
1094 dithering, and setting filler.) If this is the case, simply do this:
1096 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1098 where png_transforms is an integer containing the logical OR of
1099 some set of transformation flags. This call is equivalent to png_read_info(),
1100 followed the set of transformations indicated by the transform mask,
1101 then png_read_image(), and finally png_read_end().
1103 (The final parameter of this call is not yet used. Someday it might point
1104 to transformation parameters required by some future input transform.)
1106 After you have called png_read_png(), you can retrieve the image data
1109 row_pointers = png_get_rows(png_ptr, info_ptr);
1111 where row_pointers is an array of pointers to the pixel data for each row:
1113 png_bytep row_pointers[height];
1115 If you know your image size and pixel size ahead of time, you can allocate
1116 row_pointers prior to calling png_read_png() with
1118 row_pointers = png_malloc(png_ptr, height*sizeof(png_bytep));
1119 for (int i=0; i<height, i++)
1120 row_pointers[i]=png_malloc(png_ptr, width*pixel_size);
1121 png_set_rows(png_ptr, info_ptr, &row_pointers);
1123 Alternatively you could allocate your image in one big block and define
1124 row_pointers[i] to point into the proper places in your block.
1126 If you use png_set_rows(), the application is responsible for freeing
1127 row_pointers (and row_pointers[i], if they were separately allocated).
1129 If you don't allocate row_pointers ahead of time, png_read_png() will
1130 do it, and it'll be free'ed when you call png_destroy_*().
1132 .SS The low-level read interface
1134 If you are going the low-level route, you are now ready to read all
1135 the file information up to the actual image data. You do this with a
1136 call to png_read_info().
1138 png_read_info(png_ptr, info_ptr);
1140 This will process all chunks up to but not including the image data.
1142 .SS Querying the info structure
1144 Functions are used to get the information from the info_ptr once it
1145 has been read. Note that these fields may not be completely filled
1146 in until png_read_end() has read the chunk data following the image.
1148 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1149 &bit_depth, &color_type, &interlace_type,
1150 &compression_type, &filter_method);
1152 width - holds the width of the image
1153 in pixels (up to 2^31).
1154 height - holds the height of the image
1155 in pixels (up to 2^31).
1156 bit_depth - holds the bit depth of one of the
1157 image channels. (valid values are
1158 1, 2, 4, 8, 16 and depend also on
1159 the color_type. See also
1160 significant bits (sBIT) below).
1161 color_type - describes which color/alpha channels
1164 (bit depths 1, 2, 4, 8, 16)
1165 PNG_COLOR_TYPE_GRAY_ALPHA
1167 PNG_COLOR_TYPE_PALETTE
1168 (bit depths 1, 2, 4, 8)
1171 PNG_COLOR_TYPE_RGB_ALPHA
1174 PNG_COLOR_MASK_PALETTE
1175 PNG_COLOR_MASK_COLOR
1176 PNG_COLOR_MASK_ALPHA
1178 filter_method - (must be PNG_FILTER_TYPE_BASE
1179 for PNG 1.0, and can also be
1180 PNG_INTRAPIXEL_DIFFERENCING if
1181 the PNG datastream is embedded in
1182 a MNG-1.0 datastream)
1183 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1185 interlace_type - (PNG_INTERLACE_NONE or
1186 PNG_INTERLACE_ADAM7)
1187 Any or all of interlace_type, compression_type, of
1188 filter_method can be NULL if you are
1189 not interested in their values.
1191 channels = png_get_channels(png_ptr, info_ptr);
1192 channels - number of channels of info for the
1193 color type (valid values are 1 (GRAY,
1194 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1195 4 (RGB_ALPHA or RGB + filler byte))
1196 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1197 rowbytes - number of bytes needed to hold a row
1199 signature = png_get_signature(png_ptr, info_ptr);
1200 signature - holds the signature read from the
1201 file (if any). The data is kept in
1202 the same offset it would be if the
1203 whole signature were read (i.e. if an
1204 application had already read in 4
1205 bytes of signature before starting
1206 libpng, the remaining 4 bytes would
1207 be in signature[4] through signature[7]
1208 (see png_set_sig_bytes())).
1211 width = png_get_image_width(png_ptr,
1213 height = png_get_image_height(png_ptr,
1215 bit_depth = png_get_bit_depth(png_ptr,
1217 color_type = png_get_color_type(png_ptr,
1219 filter_method = png_get_filter_type(png_ptr,
1221 compression_type = png_get_compression_type(png_ptr,
1223 interlace_type = png_get_interlace_type(png_ptr,
1227 These are also important, but their validity depends on whether the chunk
1228 has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1229 png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1230 data has been read, or zero if it is missing. The parameters to the
1231 png_get_<chunk> are set directly if they are simple data types, or a pointer
1232 into the info_ptr is returned for any complex types.
1234 png_get_PLTE(png_ptr, info_ptr, &palette,
1236 palette - the palette for the file
1237 (array of png_color)
1238 num_palette - number of entries in the palette
1240 png_get_gAMA(png_ptr, info_ptr, &gamma);
1241 gamma - the gamma the file is written
1244 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1245 srgb_intent - the rendering intent (PNG_INFO_sRGB)
1246 The presence of the sRGB chunk
1247 means that the pixel data is in the
1248 sRGB color space. This chunk also
1249 implies specific values of gAMA and
1252 png_get_iCCP(png_ptr, info_ptr, &name, &compression_type,
1253 &profile, &proflen);
1254 name - The profile name.
1255 compression - The compression type; always PNG_COMPRESSION_TYPE_BASE
1256 for PNG 1.0. You may give NULL to this argument
1258 profile - International Color Consortium color profile
1259 data. May contain NULs.
1260 proflen - length of profile data in bytes.
1262 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1263 sig_bit - the number of significant bits for
1264 (PNG_INFO_sBIT) each of the gray,
1265 red, green, and blue channels,
1266 whichever are appropriate for the
1267 given color type (png_color_16)
1269 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
1271 trans - array of transparent entries for
1272 palette (PNG_INFO_tRNS)
1273 trans_values - graylevel or color sample values of
1274 the single transparent color for
1275 non-paletted images (PNG_INFO_tRNS)
1276 num_trans - number of transparent entries
1279 png_get_hIST(png_ptr, info_ptr, &hist);
1281 hist - histogram of palette (array of
1284 png_get_tIME(png_ptr, info_ptr, &mod_time);
1285 mod_time - time image was last modified
1288 png_get_bKGD(png_ptr, info_ptr, &background);
1289 background - background color (PNG_VALID_bKGD)
1290 valid 16-bit red, green and blue
1291 values, regardless of color_type
1293 num_comments = png_get_text(png_ptr, info_ptr,
1294 &text_ptr, &num_text);
1295 num_comments - number of comments
1296 text_ptr - array of png_text holding image
1298 text_ptr[i].compression - type of compression used
1299 on "text" PNG_TEXT_COMPRESSION_NONE
1300 PNG_TEXT_COMPRESSION_zTXt
1301 PNG_ITXT_COMPRESSION_NONE
1302 PNG_ITXT_COMPRESSION_zTXt
1303 text_ptr[i].key - keyword for comment. Must contain
1305 text_ptr[i].text - text comments for current
1306 keyword. Can be empty.
1307 text_ptr[i].text_length - length of text string,
1308 after decompression, 0 for iTXt
1309 text_ptr[i].itxt_length - length of itxt string,
1310 after decompression, 0 for tEXt/zTXt
1311 text_ptr[i].lang - language of comment (empty
1312 string for unknown).
1313 text_ptr[i].translated_keyword - keyword in UTF-8
1314 (empty string for unknown).
1315 num_text - number of comments (same as num_comments;
1316 you can put NULL here to avoid the duplication)
1317 Note while png_set_text() will accept text, language, and
1318 translated keywords that can be NULL pointers, the structure
1319 returned by png_get_text will always contain regular
1320 zero-terminated C strings. They might be empty strings but
1321 they will never be NULL pointers.
1323 num_spalettes = png_get_sPLT(png_ptr, info_ptr, &palette_ptr);
1324 palette_ptr - array of palette structures holding
1325 contents of one or more sPLT chunks read.
1326 num_spalettes - number of sPLT chunks read.
1328 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1330 offset_x - positive offset from the left edge
1332 offset_y - positive offset from the top edge
1334 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1336 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1338 res_x - pixels/unit physical resolution in
1340 res_y - pixels/unit physical resolution in
1342 unit_type - PNG_RESOLUTION_UNKNOWN,
1343 PNG_RESOLUTION_METER
1345 png_get_sCAL(png_ptr, info_ptr, &unit, &width, &height)
1346 unit - physical scale units (an integer)
1347 width - width of a pixel in physical scale units
1348 height - height of a pixel in physical scale units
1349 (width and height are doubles)
1351 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width, &height)
1352 unit - physical scale units (an integer)
1353 width - width of a pixel in physical scale units
1354 height - height of a pixel in physical scale units
1355 (width and height are strings like "2.54")
1357 num_unknown_chunks = png_get_unknown_chunks(png_ptr, info_ptr,
1359 unknowns - array of png_unknown_chunk structures holding
1361 unknowns[i].name - name of unknown chunk
1362 unknowns[i].data - data of unknown chunk
1363 unknowns[i].size - size of unknown chunk's data
1364 unknowns[i].location - position of chunk in file
1366 The value of "i" corresponds to the order in which the chunks were read
1367 from the PNG file or inserted with the png_set_unknown_chunks() function.
1369 The data from the pHYs chunk can be retrieved in several convenient
1372 res_x = png_get_x_pixels_per_meter(png_ptr,
1374 res_y = png_get_y_pixels_per_meter(png_ptr,
1376 res_x_and_y = png_get_pixels_per_meter(png_ptr,
1378 res_x = png_get_x_pixels_per_inch(png_ptr,
1380 res_y = png_get_y_pixels_per_inch(png_ptr,
1382 res_x_and_y = png_get_pixels_per_inch(png_ptr,
1384 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1387 (Each of these returns 0 [signifying "unknown"] if
1388 the data is not present or if res_x is 0;
1389 res_x_and_y is 0 if res_x != res_y)
1391 The data from the oFFs chunk can be retrieved in several convenient
1394 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1395 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1396 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1397 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1399 (Each of these returns 0 [signifying "unknown" if both
1400 x and y are 0] if the data is not present or if the chunk
1401 is present but the unit is the pixel)
1403 For more information, see the png_info definition in png.h and the
1404 PNG specification for chunk contents. Be careful with trusting
1405 rowbytes, as some of the transformations could increase the space
1406 needed to hold a row (expand, filler, gray_to_rgb, etc.).
1407 See png_read_update_info(), below.
1409 A quick word about text_ptr and num_text. PNG stores comments in
1410 keyword/text pairs, one pair per chunk, with no limit on the number
1411 of text chunks, and a 2^31 byte limit on their size. While there are
1412 suggested keywords, there is no requirement to restrict the use to these
1413 strings. It is strongly suggested that keywords and text be sensible
1414 to humans (that's the point), so don't use abbreviations. Non-printing
1415 symbols are not allowed. See the PNG specification for more details.
1416 There is also no requirement to have text after the keyword.
1418 Keywords should be limited to 79 Latin-1 characters without leading or
1419 trailing spaces, but non-consecutive spaces are allowed within the
1420 keyword. It is possible to have the same keyword any number of times.
1421 The text_ptr is an array of png_text structures, each holding a
1422 pointer to a language string, a pointer to a keyword and a pointer to
1423 a text string. The text string, language code, and translated
1424 keyword may be empty or NULL pointers. The keyword/text
1425 pairs are put into the array in the order that they are received.
1426 However, some or all of the text chunks may be after the image, so, to
1427 make sure you have read all the text chunks, don't mess with these
1428 until after you read the stuff after the image. This will be
1429 mentioned again below in the discussion that goes with png_read_end().
1431 .SS Input transformations
1433 After you've read the header information, you can set up the library
1434 to handle any special transformations of the image data. The various
1435 ways to transform the data will be described in the order that they
1436 should occur. This is important, as some of these change the color
1437 type and/or bit depth of the data, and some others only work on
1438 certain color types and bit depths. Even though each transformation
1439 checks to see if it has data that it can do something with, you should
1440 make sure to only enable a transformation if it will be valid for the
1441 data. For example, don't swap red and blue on grayscale data.
1443 The colors used for the background and transparency values should be
1444 supplied in the same format/depth as the current image data. They
1445 are stored in the same format/depth as the image data in a bKGD or tRNS
1446 chunk, so this is what libpng expects for this data. The colors are
1447 transformed to keep in sync with the image data when an application
1448 calls the png_read_update_info() routine (see below).
1450 Data will be decoded into the supplied row buffers packed into bytes
1451 unless the library has been told to transform it into another format.
1452 For example, 4 bit/pixel paletted or grayscale data will be returned
1453 2 pixels/byte with the leftmost pixel in the high-order bits of the
1454 byte, unless png_set_packing() is called. 8-bit RGB data will be stored
1455 in RGB RGB RGB format unless png_set_filler() is called to insert filler
1456 bytes, either before or after each RGB triplet. 16-bit RGB data will
1457 be returned RRGGBB RRGGBB, with the most significant byte of the color
1458 value first, unless png_set_strip_16() is called to transform it to
1459 regular RGB RGB triplets, or png_set_filler() is called to insert
1460 filler bytes, either before or after each RRGGBB triplet. Similarly,
1461 8-bit or 16-bit grayscale data can be modified with png_set_filler()
1462 or png_set_strip_16().
1464 The following code transforms grayscale images of less than 8 to 8 bits,
1465 changes paletted images to RGB, and adds a full alpha channel if there is
1466 transparency information in a tRNS chunk. This is most useful on
1467 grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1468 viewing application that wishes to treat all images in the same way.
1470 if (color_type == PNG_COLOR_TYPE_PALETTE)
1471 png_set_palette_to_rgb(png_ptr);
1473 if (color_type == PNG_COLOR_TYPE_GRAY &&
1474 bit_depth < 8) png_set_gray_1_2_4_to_8(png_ptr);
1476 if (png_get_valid(png_ptr, info_ptr,
1477 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1479 These three functions are actually aliases for png_set_expand(), added
1480 in libpng version 1.0.4, with the function names expanded to improve code
1481 readability. In some future version they may actually do different
1484 PNG can have files with 16 bits per channel. If you only can handle
1485 8 bits per channel, this will strip the pixels down to 8 bit.
1487 if (bit_depth == 16)
1488 png_set_strip_16(png_ptr);
1490 If, for some reason, you don't need the alpha channel on an image,
1491 and you want to remove it rather than combining it with the background
1492 (but the image author certainly had in mind that you *would* combine
1493 it with the background, so that's what you should probably do):
1495 if (color_type & PNG_COLOR_MASK_ALPHA)
1496 png_set_strip_alpha(png_ptr);
1498 In PNG files, the alpha channel in an image
1499 is the level of opacity. If you need the alpha channel in an image to
1500 be the level of transparency instead of opacity, you can invert the
1501 alpha channel (or the tRNS chunk data) after it's read, so that 0 is
1502 fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
1503 images) is fully transparent, with
1505 png_set_invert_alpha(png_ptr);
1507 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1508 they can, resulting in, for example, 8 pixels per byte for 1 bit
1509 files. This code expands to 1 pixel per byte without changing the
1510 values of the pixels:
1513 png_set_packing(png_ptr);
1515 PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1516 stored in a PNG image have been "scaled" or "shifted" up to the next
1517 higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
1518 8 bits/sample in the range [0, 255]). However, it is also possible to
1519 convert the PNG pixel data back to the original bit depth of the image.
1520 This call reduces the pixels back down to the original bit depth:
1522 png_color_16p sig_bit;
1524 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1525 png_set_shift(png_ptr, sig_bit);
1527 PNG files store 3-color pixels in red, green, blue order. This code
1528 changes the storage of the pixels to blue, green, red:
1530 if (color_type == PNG_COLOR_TYPE_RGB ||
1531 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1532 png_set_bgr(png_ptr);
1534 PNG files store RGB pixels packed into 3 bytes. This code expands them
1535 into 4 bytes for windowing systems that need them in this format:
1537 if (bit_depth == 8 && color_type ==
1538 PNG_COLOR_TYPE_RGB) png_set_filler(png_ptr,
1539 filler, PNG_FILLER_BEFORE);
1541 where "filler" is the 8 or 16-bit number to fill with, and the location is
1542 either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1543 you want the filler before the RGB or after. This transformation
1544 does not affect images that already have full alpha channels.
1546 If you are reading an image with an alpha channel, and you need the
1547 data as ARGB instead of the normal PNG format RGBA:
1549 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1550 png_set_swap_alpha(png_ptr);
1552 For some uses, you may want a grayscale image to be represented as
1553 RGB. This code will do that conversion:
1555 if (color_type == PNG_COLOR_TYPE_GRAY ||
1556 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1557 png_set_gray_to_rgb(png_ptr);
1559 Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1562 if (color_type == PNG_COLOR_TYPE_RGB ||
1563 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1564 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1565 int red_weight, int green_weight);
1567 error_action = 1: silently do the conversion
1568 error_action = 2: issue a warning if the original
1569 image has any pixel where
1570 red != green or red != blue
1571 error_action = 3: issue an error and abort the
1572 conversion if the original
1573 image has any pixel where
1574 red != green or red != blue
1576 red_weight: weight of red component times 100000
1577 green_weight: weight of green component times 100000
1578 If either weight is negative, default
1579 weights (21268, 71514) are used.
1581 If you have set error_action = 1 or 2, you can
1582 later check whether the image really was gray, after processing
1583 the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1584 It will return a png_byte that is zero if the image was gray or
1585 1 if there were any non-gray pixels. bKGD and sBIT data
1586 will be silently converted to grayscale, using the green channel
1587 data, regardless of the error_action setting.
1589 With red_weight+green_weight<=100000,
1590 the normalized graylevel is computed:
1592 int rw = red_weight * 65536;
1593 int gw = green_weight * 65536;
1594 int bw = 65536 - (rw + gw);
1595 gray = (rw*red + gw*green + bw*blue)/65536;
1597 The default values approximate those recommended in the Charles
1598 Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
1599 Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net
1601 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1603 Libpng approximates this with
1605 Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
1607 which can be expressed with integers as
1609 Y = (6969 * R + 23434 * G + 2365 * B)/32768
1611 The calculation is done in a linear colorspace, if the image gamma
1614 If you have a grayscale and you are using png_set_expand_depth() or
1615 png_set_expand() to change to
1616 a higher bit-depth, you must either supply the background color as a gray
1617 value at the original file bit-depth (need_expand = 1) or else supply the
1618 background color as an RGB triplet at the final, expanded bit depth
1619 (need_expand = 0). Similarly, if you are reading a paletted image, you
1620 must either supply the background color as a palette index (need_expand = 1)
1621 or as an RGB triplet that may or may not be in the palette (need_expand = 0).
1623 png_color_16 my_background;
1624 png_color_16p image_background;
1626 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1627 png_set_background(png_ptr, image_background,
1628 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
1630 png_set_background(png_ptr, &my_background,
1631 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1633 The png_set_background() function tells libpng to composite images
1634 with alpha or simple transparency against the supplied background
1635 color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1636 you may use this color, or supply another color more suitable for
1637 the current display (e.g., the background color from a web page). You
1638 need to tell libpng whether the color is in the gamma space of the
1639 display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
1640 (PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
1641 that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
1642 know why anyone would use this, but it's here).
1644 To properly display PNG images on any kind of system, the application needs
1645 to know what the display gamma is. Ideally, the user will know this, and
1646 the application will allow them to set it. One method of allowing the user
1647 to set the display gamma separately for each system is to check for a
1648 SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
1651 Note that display_gamma is the overall gamma correction required to produce
1652 pleasing results, which depends on the lighting conditions in the surrounding
1653 environment. In a dim or brightly lit room, no compensation other than
1654 the physical gamma exponent of the monitor is needed, while in a dark room
1655 a slightly smaller exponent is better.
1657 double gamma, screen_gamma;
1659 if (/* We have a user-defined screen
1662 screen_gamma = user_defined_screen_gamma;
1664 /* One way that applications can share the same
1665 screen gamma value */
1666 else if ((gamma_str = getenv("SCREEN_GAMMA"))
1669 screen_gamma = (double)atof(gamma_str);
1671 /* If we don't have another value */
1674 screen_gamma = 2.2; /* A good guess for a
1675 PC monitor in a bright office or a dim room */
1676 screen_gamma = 2.0; /* A good guess for a
1677 PC monitor in a dark room */
1678 screen_gamma = 1.7 or 1.0; /* A good
1679 guess for Mac systems */
1682 The png_set_gamma() function handles gamma transformations of the data.
1683 Pass both the file gamma and the current screen_gamma. If the file does
1684 not have a gamma value, you can pass one anyway if you have an idea what
1685 it is (usually 0.45455 is a good guess for GIF images on PCs). Note
1686 that file gammas are inverted from screen gammas. See the discussions
1687 on gamma in the PNG specification for an excellent description of what
1688 gamma is, and why all applications should support it. It is strongly
1689 recommended that PNG viewers support gamma correction.
1691 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1692 png_set_gamma(png_ptr, screen_gamma, gamma);
1694 png_set_gamma(png_ptr, screen_gamma, 0.45455);
1696 If you need to reduce an RGB file to a paletted file, or if a paletted
1697 file has more entries then will fit on your screen, png_set_dither()
1698 will do that. Note that this is a simple match dither that merely
1699 finds the closest color available. This should work fairly well with
1700 optimized palettes, and fairly badly with linear color cubes. If you
1701 pass a palette that is larger then maximum_colors, the file will
1702 reduce the number of colors in the palette so it will fit into
1703 maximum_colors. If there is a histogram, it will use it to make
1704 more intelligent choices when reducing the palette. If there is no
1705 histogram, it may not do as good a job.
1707 if (color_type & PNG_COLOR_MASK_COLOR)
1709 if (png_get_valid(png_ptr, info_ptr,
1712 png_uint_16p histogram;
1714 png_get_hIST(png_ptr, info_ptr,
1716 png_set_dither(png_ptr, palette, num_palette,
1717 max_screen_colors, histogram, 1);
1721 png_color std_color_cube[MAX_SCREEN_COLORS] =
1724 png_set_dither(png_ptr, std_color_cube,
1725 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1730 PNG files describe monochrome as black being zero and white being one.
1731 The following code will reverse this (make black be one and white be
1734 if (bit_depth == 1 && color_type == PNG_COLOR_GRAY)
1735 png_set_invert_mono(png_ptr);
1737 PNG files store 16 bit pixels in network byte order (big-endian,
1738 ie. most significant bits first). This code changes the storage to the
1739 other way (little-endian, i.e. least significant bits first, the
1740 way PCs store them):
1742 if (bit_depth == 16)
1743 png_set_swap(png_ptr);
1745 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1746 need to change the order the pixels are packed into bytes, you can use:
1749 png_set_packswap(png_ptr);
1751 Finally, you can write your own transformation function if none of
1752 the existing ones meets your needs. This is done by setting a callback
1755 png_set_read_user_transform_fn(png_ptr,
1758 You must supply the function
1760 void read_transform_fn(png_ptr ptr, row_info_ptr
1761 row_info, png_bytep data)
1763 See pngtest.c for a working example. Your function will be called
1764 after all of the other transformations have been processed.
1766 You can also set up a pointer to a user structure for use by your
1767 callback function, and you can inform libpng that your transform
1768 function will change the number of channels or bit depth with the
1771 png_set_user_transform_info(png_ptr, user_ptr,
1772 user_depth, user_channels);
1774 The user's application, not libpng, is responsible for allocating and
1775 freeing any memory required for the user structure.
1777 You can retrieve the pointer via the function
1778 png_get_user_transform_ptr(). For example:
1780 voidp read_user_transform_ptr =
1781 png_get_user_transform_ptr(png_ptr);
1783 The last thing to handle is interlacing; this is covered in detail below,
1784 but you must call the function here if you want libpng to handle expansion
1785 of the interlaced image.
1787 number_of_passes = png_set_interlace_handling(png_ptr);
1789 After setting the transformations, libpng can update your png_info
1790 structure to reflect any transformations you've requested with this
1791 call. This is most useful to update the info structure's rowbytes
1792 field so you can use it to allocate your image memory. This function
1793 will also update your palette with the correct screen_gamma and
1794 background if these have been given with the calls above.
1796 png_read_update_info(png_ptr, info_ptr);
1798 After you call png_read_update_info(), you can allocate any
1799 memory you need to hold the image. The row data is simply
1800 raw byte data for all forms of images. As the actual allocation
1801 varies among applications, no example will be given. If you
1802 are allocating one large chunk, you will need to build an
1803 array of pointers to each row, as it will be needed for some
1804 of the functions below.
1806 .SS Reading image data
1808 After you've allocated memory, you can read the image data.
1809 The simplest way to do this is in one function call. If you are
1810 allocating enough memory to hold the whole image, you can just
1811 call png_read_image() and libpng will read in all the image data
1812 and put it in the memory area supplied. You will need to pass in
1813 an array of pointers to each row.
1815 This function automatically handles interlacing, so you don't need
1816 to call png_set_interlace_handling() or call this function multiple
1817 times, or any of that other stuff necessary with png_read_rows().
1819 png_read_image(png_ptr, row_pointers);
1821 where row_pointers is:
1823 png_bytep row_pointers[height];
1825 You can point to void or char or whatever you use for pixels.
1827 If you don't want to read in the whole image at once, you can
1828 use png_read_rows() instead. If there is no interlacing (check
1829 interlace_type == PNG_INTERLACE_NONE), this is simple:
1831 png_read_rows(png_ptr, row_pointers, NULL,
1834 where row_pointers is the same as in the png_read_image() call.
1836 If you are doing this just one row at a time, you can do this with
1837 a single row_pointer instead of an array of row_pointers:
1839 png_bytep row_pointer = row;
1840 png_read_row(png_ptr, row_pointer, NULL);
1842 If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1843 get somewhat harder. The only current (PNG Specification version 1.2)
1844 interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
1845 is a somewhat complicated 2D interlace scheme, known as Adam7, that
1846 breaks down an image into seven smaller images of varying size, based
1849 libpng can fill out those images or it can give them to you "as is".
1850 If you want them filled out, there are two ways to do that. The one
1851 mentioned in the PNG specification is to expand each pixel to cover
1852 those pixels that have not been read yet (the "rectangle" method).
1853 This results in a blocky image for the first pass, which gradually
1854 smooths out as more pixels are read. The other method is the "sparkle"
1855 method, where pixels are drawn only in their final locations, with the
1856 rest of the image remaining whatever colors they were initialized to
1857 before the start of the read. The first method usually looks better,
1858 but tends to be slower, as there are more pixels to put in the rows.
1860 If you don't want libpng to handle the interlacing details, just call
1861 png_read_rows() seven times to read in all seven images. Each of the
1862 images is a valid image by itself, or they can all be combined on an
1863 8x8 grid to form a single image (although if you intend to combine them
1864 you would be far better off using the libpng interlace handling).
1866 The first pass will return an image 1/8 as wide as the entire image
1867 (every 8th column starting in column 0) and 1/8 as high as the original
1868 (every 8th row starting in row 0), the second will be 1/8 as wide
1869 (starting in column 4) and 1/8 as high (also starting in row 0). The
1870 third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
1871 1/8 as high (every 8th row starting in row 4), and the fourth pass will
1872 be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
1873 and every 4th row starting in row 0). The fifth pass will return an
1874 image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
1875 while the sixth pass will be 1/2 as wide and 1/2 as high as the original
1876 (starting in column 1 and row 0). The seventh and final pass will be as
1877 wide as the original, and 1/2 as high, containing all of the odd
1878 numbered scanlines. Phew!
1880 If you want libpng to expand the images, call this before calling
1881 png_start_read_image() or png_read_update_info():
1883 if (interlace_type == PNG_INTERLACE_ADAM7)
1885 = png_set_interlace_handling(png_ptr);
1887 This will return the number of passes needed. Currently, this
1888 is seven, but may change if another interlace type is added.
1889 This function can be called even if the file is not interlaced,
1890 where it will return one pass.
1892 If you are not going to display the image after each pass, but are
1893 going to wait until the entire image is read in, use the sparkle
1894 effect. This effect is faster and the end result of either method
1895 is exactly the same. If you are planning on displaying the image
1896 after each pass, the "rectangle" effect is generally considered the
1899 If you only want the "sparkle" effect, just call png_read_rows() as
1900 normal, with the third parameter NULL. Make sure you make pass over
1901 the image number_of_passes times, and you don't change the data in the
1902 rows between calls. You can change the locations of the data, just
1903 not the data. Each pass only writes the pixels appropriate for that
1904 pass, and assumes the data from previous passes is still valid.
1906 png_read_rows(png_ptr, row_pointers, NULL,
1909 If you only want the first effect (the rectangles), do the same as
1910 before except pass the row buffer in the third parameter, and leave
1911 the second parameter NULL.
1913 png_read_rows(png_ptr, NULL, row_pointers,
1916 .SS Finishing a sequential read
1918 After you are finished reading the image through either the high- or
1919 low-level interfaces, you can finish reading the file. If you are
1920 interested in comments or time, which may be stored either before or
1921 after the image data, you should pass the separate png_info struct if
1922 you want to keep the comments from before and after the image
1923 separate. If you are not interested, you can pass NULL.
1925 png_read_end(png_ptr, end_info);
1927 When you are done, you can free all memory allocated by libpng like this:
1929 png_destroy_read_struct(&png_ptr, &info_ptr,
1932 It is also possible to individually free the info_ptr members that
1933 point to libpng-allocated storage with the following function:
1935 png_free_data(png_ptr, info_ptr, mask, n)
1936 mask - identifies data to be freed, a mask
1937 containing the logical OR of one or
1939 PNG_FREE_PLTE, PNG_FREE_TRNS,
1940 PNG_FREE_HIST, PNG_FREE_ICCP,
1941 PNG_FREE_PCAL, PNG_FREE_ROWS,
1942 PNG_FREE_SCAL, PNG_FREE_SPLT,
1943 PNG_FREE_TEXT, PNG_FREE_UNKN,
1944 or simply PNG_FREE_ALL
1945 n - sequence number of item to be freed
1948 This function may be safely called when the relevant storage has
1949 already been freed, or has not yet been allocated, or was allocated
1950 by the user and not by libpng, and will in those
1951 cases do nothing. The "n" parameter is ignored if only one item
1952 of the selected data type, such as PLTE, is allowed. If "n" is not
1953 -1, and multiple items are allowed for the data type identified in
1954 the mask, such as text or sPLT, only the n'th item is freed.
1956 The default behavior is only to free data that was allocated internally
1957 by libpng. This can be changed, so that libpng will not free the data,
1958 or so that it will free data that was allocated by the user with png_malloc()
1959 or png_zalloc() and passed in via a png_set_*() function, with
1961 png_data_freer(png_ptr, info_ptr, freer, mask)
1962 mask - which data elements are affected
1963 same choices as in png_free_data()
1965 PNG_DESTROY_WILL_FREE_DATA
1966 PNG_SET_WILL_FREE_DATA
1967 PNG_USER_WILL_FREE_DATA
1969 This function only affects data that has already been allocated.
1970 You can call this function after reading the PNG data but before calling
1971 any png_set_*() functions, to control whether the user or the png_set_*()
1972 function is responsible for freeing any existing data that might be present,
1973 and again after the png_set_*() functions to control whether the user
1974 or png_destroy_*() is supposed to free the data. When the user assumes
1975 responsibility for libpng-allocated data, the application must use
1976 png_free() to free it, and when the user transfers responsibility to libpng
1977 for data that the user has allocated, the user must have used png_malloc()
1978 or png_zalloc() to allocate it (the png_zalloc() function is the same
1979 as png_malloc() except that it also zeroes the newly-allocated memory).
1981 If you allocated your row_pointers in a single block, as suggested above in
1982 the description of the high level read interface, you must not transfer
1983 responsibility for freeing it to the png_set_rows or png_read_destroy function,
1984 because they would also try to free the individual row_pointers[i].
1986 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
1987 separately, do not transfer responsibility for freeing text_ptr to libpng,
1988 because when libpng fills a png_text structure it combines these members with
1989 the key member, and png_free_data() will free only text_ptr.key. Similarly,
1990 if you transfer responsibility for free'ing text_ptr from libpng to your
1991 application, your application must not separately free those members.
1993 The png_free_data() function will turn off the "valid" flag for anything
1994 it frees. If you need to turn the flag off for a chunk that was freed by your
1995 application instead of by libpng, you can use
1997 png_set_invalid(png_ptr, info_ptr, mask);
1998 mask - identifies the chunks to be made invalid,
1999 containing the logical OR of one or
2001 PNG_INFO_gAMA, PNG_INFO_sBIT,
2002 PNG_INFO_cHRM, PNG_INFO_PLTE,
2003 PNG_INFO_tRNS, PNG_INFO_bKGD,
2004 PNG_INFO_hIST, PNG_INFO_pHYs,
2005 PNG_INFO_oFFs, PNG_INFO_tIME,
2006 PNG_INFO_pCAL, PNG_INFO_sRGB,
2007 PNG_INFO_iCCP, PNG_INFO_sPLT,
2008 PNG_INFO_sCAL, PNG_INFO_IDAT
2010 For a more compact example of reading a PNG image, see the file example.c.
2012 .SS Reading PNG files progressively
2014 The progressive reader is slightly different then the non-progressive
2015 reader. Instead of calling png_read_info(), png_read_rows(), and
2016 png_read_end(), you make one call to png_process_data(), which calls
2017 callbacks when it has the info, a row, or the end of the image. You
2018 set up these callbacks with png_set_progressive_read_fn(). You don't
2019 have to worry about the input/output functions of libpng, as you are
2020 giving the library the data directly in png_process_data(). I will
2021 assume that you have read the section on reading PNG files above,
2022 so I will only highlight the differences (although I will show
2025 png_structp png_ptr;
2028 /* An example code fragment of how you would
2029 initialize the progressive reader in your
2032 initialize_png_reader()
2034 png_ptr = png_create_read_struct
2035 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2036 user_error_fn, user_warning_fn);
2039 info_ptr = png_create_info_struct(png_ptr);
2042 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
2047 if (setjmp(png_jmpbuf(png_ptr)))
2049 png_destroy_read_struct(&png_ptr, &info_ptr,
2054 /* This one's new. You can provide functions
2055 to be called when the header info is valid,
2056 when each row is completed, and when the image
2057 is finished. If you aren't using all functions,
2058 you can specify NULL parameters. Even when all
2059 three functions are NULL, you need to call
2060 png_set_progressive_read_fn(). You can use
2061 any struct as the user_ptr (cast to a void pointer
2062 for the function call), and retrieve the pointer
2063 from inside the callbacks using the function
2065 png_get_progressive_ptr(png_ptr);
2067 which will return a void pointer, which you have
2068 to cast appropriately.
2070 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2071 info_callback, row_callback, end_callback);
2076 /* A code fragment that you call as you receive blocks
2079 process_data(png_bytep buffer, png_uint_32 length)
2081 if (setjmp(png_jmpbuf(png_ptr)))
2083 png_destroy_read_struct(&png_ptr, &info_ptr,
2088 /* This one's new also. Simply give it a chunk
2089 of data from the file stream (in order, of
2090 course). On machines with segmented memory
2091 models machines, don't give it any more than
2092 64K. The library seems to run fine with sizes
2093 of 4K. Although you can give it much less if
2094 necessary (I assume you can give it chunks of
2095 1 byte, I haven't tried less then 256 bytes
2096 yet). When this function returns, you may
2097 want to display any rows that were generated
2098 in the row callback if you don't already do
2101 png_process_data(png_ptr, info_ptr, buffer, length);
2105 /* This function is called (as set by
2106 png_set_progressive_read_fn() above) when enough data
2107 has been supplied so all of the header has been
2111 info_callback(png_structp png_ptr, png_infop info)
2113 /* Do any setup here, including setting any of
2114 the transformations mentioned in the Reading
2115 PNG files section. For now, you _must_ call
2116 either png_start_read_image() or
2117 png_read_update_info() after all the
2118 transformations are set (even if you don't set
2119 any). You may start getting rows before
2120 png_process_data() returns, so this is your
2121 last chance to prepare for that.
2125 /* This function is called when each row of image
2128 row_callback(png_structp png_ptr, png_bytep new_row,
2129 png_uint_32 row_num, int pass)
2131 /* If the image is interlaced, and you turned
2132 on the interlace handler, this function will
2133 be called for every row in every pass. Some
2134 of these rows will not be changed from the
2135 previous pass. When the row is not changed,
2136 the new_row variable will be NULL. The rows
2137 and passes are called in order, so you don't
2138 really need the row_num and pass, but I'm
2139 supplying them because it may make your life
2142 For the non-NULL rows of interlaced images,
2143 you must call png_progressive_combine_row()
2144 passing in the row and the old row. You can
2145 call this function for NULL rows (it will just
2146 return) and for non-interlaced images (it just
2147 does the memcpy for you) if it will make the
2148 code easier. Thus, you can just do this for
2152 png_progressive_combine_row(png_ptr, old_row,
2155 /* where old_row is what was displayed for
2156 previously for the row. Note that the first
2157 pass (pass == 0, really) will completely cover
2158 the old row, so the rows do not have to be
2159 initialized. After the first pass (and only
2160 for interlaced images), you will have to pass
2161 the current row, and the function will combine
2162 the old row and the new row.
2167 end_callback(png_structp png_ptr, png_infop info)
2169 /* This function is called after the whole image
2170 has been read, including any chunks after the
2171 image (up to and including the IEND). You
2172 will usually have the same info chunk as you
2173 had in the header, although some data may have
2174 been added to the comments and time fields.
2176 Most people won't do much here, perhaps setting
2177 a flag that marks the image as finished.
2185 Much of this is very similar to reading. However, everything of
2186 importance is repeated here, so you won't have to constantly look
2187 back up in the reading section to understand writing.
2191 You will want to do the I/O initialization before you get into libpng,
2192 so if it doesn't work, you don't have anything to undo. If you are not
2193 using the standard I/O functions, you will need to replace them with
2194 custom writing functions. See the discussion under Customizing libpng.
2196 FILE *fp = fopen(file_name, "wb");
2202 Next, png_struct and png_info need to be allocated and initialized.
2203 As these can be both relatively large, you may not want to store these
2204 on the stack, unless you have stack space to spare. Of course, you
2205 will want to check if they return NULL. If you are also reading,
2206 you won't want to name your read structure and your write structure
2207 both "png_ptr"; you can call them anything you like, such as
2208 "read_ptr" and "write_ptr". Look at pngtest.c, for example.
2210 png_structp png_ptr = png_create_write_struct
2211 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2212 user_error_fn, user_warning_fn);
2216 png_infop info_ptr = png_create_info_struct(png_ptr);
2219 png_destroy_write_struct(&png_ptr,
2224 If you want to use your own memory allocation routines,
2225 define PNG_USER_MEM_SUPPORTED and use
2226 png_create_write_struct_2() instead of png_create_write_struct():
2228 png_structp png_ptr = png_create_write_struct_2
2229 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2230 user_error_fn, user_warning_fn, (png_voidp)
2231 user_mem_ptr, user_malloc_fn, user_free_fn);
2233 After you have these structures, you will need to set up the
2234 error handling. When libpng encounters an error, it expects to
2235 longjmp() back to your routine. Therefore, you will need to call
2236 setjmp() and pass the png_jmpbuf(png_ptr). If you
2237 write the file from different routines, you will need to update
2238 the png_jmpbuf(png_ptr) every time you enter a new routine that will
2239 call a png_*() function. See your documentation of setjmp/longjmp
2240 for your compiler for more information on setjmp/longjmp. See
2241 the discussion on libpng error handling in the Customizing Libpng
2242 section below for more information on the libpng error handling.
2244 if (setjmp(png_jmpbuf(png_ptr)))
2246 png_destroy_write_struct(&png_ptr, &info_ptr);
2253 If you would rather avoid the complexity of setjmp/longjmp issues,
2254 you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
2255 errors will result in a call to PNG_ABORT() which defaults to abort().
2257 Now you need to set up the output code. The default for libpng is to
2258 use the C function fwrite(). If you use this, you will need to pass a
2259 valid FILE * in the function png_init_io(). Be sure that the file is
2260 opened in binary mode. Again, if you wish to handle writing data in
2261 another way, see the discussion on libpng I/O handling in the Customizing
2262 Libpng section below.
2264 png_init_io(png_ptr, fp);
2268 At this point, you can set up a callback function that will be
2269 called after each row has been written, which you can use to control
2270 a progress meter or the like. It's demonstrated in pngtest.c.
2271 You must supply a function
2273 void write_row_callback(png_ptr, png_uint_32 row, int pass);
2275 /* put your code here */
2278 (You can give it another name that you like instead of "write_row_callback")
2280 To inform libpng about your function, use
2282 png_set_write_status_fn(png_ptr, write_row_callback);
2284 You now have the option of modifying how the compression library will
2285 run. The following functions are mainly for testing, but may be useful
2286 in some cases, like if you need to write PNG files extremely fast and
2287 are willing to give up some compression, or if you want to get the
2288 maximum possible compression at the expense of slower writing. If you
2289 have no special needs in this area, let the library do what it wants by
2290 not calling this function at all, as it has been tuned to deliver a good
2291 speed/compression ratio. The second parameter to png_set_filter() is
2292 the filter method, for which the only valid values are 0 (as of the
2293 July 1999 PNG specification, version 1.2) or 64 (if you are writing
2294 a PNG datastream that is to be embedded in a MNG datastream). The third
2295 parameter is a flag that indicates which filter type(s) are to be tested
2296 for each scanline. See the PNG specification for details on the specific filter
2300 /* turn on or off filtering, and/or choose
2301 specific filters. You can use either a single PNG_FILTER_VALUE_NAME
2302 or the logical OR of one or more PNG_FILTER_NAME masks. */
2303 png_set_filter(png_ptr, 0,
2304 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
2305 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
2306 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
2307 PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE |
2308 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2312 wants to start and stop using particular filters during compression,
2313 it should start out with all of the filters (to ensure that the previous
2314 row of pixels will be stored in case it's needed later), and then add
2315 and remove them after the start of compression.
2317 If you are writing a PNG datastream that is to be embedded in a MNG
2318 datastream, the second parameter can be either 0 or 64.
2320 The png_set_compression_*() functions interface to the zlib compression
2321 library, and should mostly be ignored unless you really know what you are
2322 doing. The only generally useful call is png_set_compression_level()
2323 which changes how much time zlib spends on trying to compress the image
2324 data. See the Compression Library (zlib.h and algorithm.txt, distributed
2325 with zlib) for details on the compression levels.
2327 /* set the zlib compression level */
2328 png_set_compression_level(png_ptr,
2329 Z_BEST_COMPRESSION);
2331 /* set other zlib parameters */
2332 png_set_compression_mem_level(png_ptr, 8);
2333 png_set_compression_strategy(png_ptr,
2334 Z_DEFAULT_STRATEGY);
2335 png_set_compression_window_bits(png_ptr, 15);
2336 png_set_compression_method(png_ptr, 8);
2337 png_set_compression_buffer_size(png_ptr, 8192)
2339 extern PNG_EXPORT(void,png_set_zbuf_size)
2341 .SS Setting the contents of info for output
2343 You now need to fill in the png_info structure with all the data you
2344 wish to write before the actual image. Note that the only thing you
2345 are allowed to write after the image is the text chunks and the time
2346 chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
2347 the latest PNG specification for more information on that. If you
2348 wish to write them before the image, fill them in now, and flag that
2349 data as being valid. If you want to wait until after the data, don't
2350 fill them until png_write_end(). For all the fields in png_info and
2351 their data types, see png.h. For explanations of what the fields
2352 contain, see the PNG specification.
2354 Some of the more important parts of the png_info are:
2356 png_set_IHDR(png_ptr, info_ptr, width, height,
2357 bit_depth, color_type, interlace_type,
2358 compression_type, filter_method)
2359 width - holds the width of the image
2360 in pixels (up to 2^31).
2361 height - holds the height of the image
2362 in pixels (up to 2^31).
2363 bit_depth - holds the bit depth of one of the
2365 (valid values are 1, 2, 4, 8, 16
2366 and depend also on the
2367 color_type. See also significant
2369 color_type - describes which color/alpha
2370 channels are present.
2372 (bit depths 1, 2, 4, 8, 16)
2373 PNG_COLOR_TYPE_GRAY_ALPHA
2375 PNG_COLOR_TYPE_PALETTE
2376 (bit depths 1, 2, 4, 8)
2379 PNG_COLOR_TYPE_RGB_ALPHA
2382 PNG_COLOR_MASK_PALETTE
2383 PNG_COLOR_MASK_COLOR
2384 PNG_COLOR_MASK_ALPHA
2386 interlace_type - PNG_INTERLACE_NONE or
2388 compression_type - (must be
2389 PNG_COMPRESSION_TYPE_DEFAULT)
2390 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
2391 or, if you are writing a PNG to
2392 be embedded in a MNG datastream,
2394 PNG_INTRAPIXEL_DIFFERENCING)
2396 png_set_PLTE(png_ptr, info_ptr, palette,
2398 palette - the palette for the file
2399 (array of png_color)
2400 num_palette - number of entries in the palette
2402 png_set_gAMA(png_ptr, info_ptr, gamma);
2403 gamma - the gamma the image was created
2406 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2407 srgb_intent - the rendering intent
2408 (PNG_INFO_sRGB) The presence of
2409 the sRGB chunk means that the pixel
2410 data is in the sRGB color space.
2411 This chunk also implies specific
2412 values of gAMA and cHRM. Rendering
2413 intent is the CSS-1 property that
2414 has been defined by the International
2416 (http://www.color.org).
2418 PNG_sRGB_INTENT_SATURATION,
2419 PNG_sRGB_INTENT_PERCEPTUAL,
2420 PNG_sRGB_INTENT_ABSOLUTE, or
2421 PNG_sRGB_INTENT_RELATIVE.
2424 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2426 srgb_intent - the rendering intent
2427 (PNG_INFO_sRGB) The presence of the
2428 sRGB chunk means that the pixel
2429 data is in the sRGB color space.
2430 This function also causes gAMA and
2431 cHRM chunks with the specific values
2432 that are consistent with sRGB to be
2435 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2437 name - The profile name.
2438 compression - The compression type; always PNG_COMPRESSION_TYPE_BASE
2439 for PNG 1.0. You may give NULL to this argument
2441 profile - International Color Consortium color profile
2442 data. May contain NULs.
2443 proflen - length of profile data in bytes.
2445 png_set_sBIT(png_ptr, info_ptr, sig_bit);
2446 sig_bit - the number of significant bits for
2447 (PNG_INFO_sBIT) each of the gray, red,
2448 green, and blue channels, whichever are
2449 appropriate for the given color type
2452 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2454 trans - array of transparent entries for
2455 palette (PNG_INFO_tRNS)
2456 trans_values - graylevel or color sample values of
2457 the single transparent color for
2458 non-paletted images (PNG_INFO_tRNS)
2459 num_trans - number of transparent entries
2462 png_set_hIST(png_ptr, info_ptr, hist);
2464 hist - histogram of palette (array of
2467 png_set_tIME(png_ptr, info_ptr, mod_time);
2468 mod_time - time image was last modified
2471 png_set_bKGD(png_ptr, info_ptr, background);
2472 background - background color (PNG_VALID_bKGD)
2474 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2475 text_ptr - array of png_text holding image
2477 text_ptr[i].compression - type of compression used
2478 on "text" PNG_TEXT_COMPRESSION_NONE
2479 PNG_TEXT_COMPRESSION_zTXt
2480 PNG_ITXT_COMPRESSION_NONE
2481 PNG_ITXT_COMPRESSION_zTXt
2482 text_ptr[i].key - keyword for comment. Must contain
2484 text_ptr[i].text - text comments for current
2485 keyword. Can be NULL or empty.
2486 text_ptr[i].text_length - length of text string,
2487 after decompression, 0 for iTXt
2488 text_ptr[i].itxt_length - length of itxt string,
2489 after decompression, 0 for tEXt/zTXt
2490 text_ptr[i].lang - language of comment (NULL or
2492 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
2493 or empty for unknown).
2494 num_text - number of comments
2496 png_set_sPLT(png_ptr, info_ptr, &palette_ptr, num_spalettes);
2497 palette_ptr - array of png_sPLT_struct structures to be
2498 added to the list of palettes in the info
2500 num_spalettes - number of palette structures to be added.
2502 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2504 offset_x - positive offset from the left
2506 offset_y - positive offset from the top
2508 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2510 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2512 res_x - pixels/unit physical resolution
2514 res_y - pixels/unit physical resolution
2516 unit_type - PNG_RESOLUTION_UNKNOWN,
2517 PNG_RESOLUTION_METER
2519 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2520 unit - physical scale units (an integer)
2521 width - width of a pixel in physical scale units
2522 height - height of a pixel in physical scale units
2523 (width and height are doubles)
2525 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2526 unit - physical scale units (an integer)
2527 width - width of a pixel in physical scale units
2528 height - height of a pixel in physical scale units
2529 (width and height are strings like "2.54")
2531 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns, num_unknowns)
2532 unknowns - array of png_unknown_chunk structures holding
2534 unknowns[i].name - name of unknown chunk
2535 unknowns[i].data - data of unknown chunk
2536 unknowns[i].size - size of unknown chunk's data
2537 unknowns[i].location - position to write chunk in file
2538 0: do not write chunk
2539 PNG_HAVE_IHDR: before PLTE
2540 PNG_HAVE_PLTE: before IDAT
2541 PNG_AFTER_IDAT: after IDAT
2542 The "location" member is set automatically according to
2543 what part of the output file has already been written.
2544 You can change its value after calling png_set_unknown_chunks()
2545 as demonstrated in pngtest.c. Within each of the "locations",
2546 the chunks are sequenced according to their position in the
2547 structure (that is, the value of "i", which is the order in which
2548 the chunk was either read from the input file or defined with
2549 png_set_unknown_chunks).
2551 A quick word about text and num_text. text is an array of png_text
2552 structures. num_text is the number of valid structures in the array.
2553 Each png_text structure holds a language code, a keyword, a text value,
2554 and a compression type.
2556 The compression types have the same valid numbers as the compression
2557 types of the image data. Currently, the only valid number is zero.
2558 However, you can store text either compressed or uncompressed, unlike
2559 images, which always have to be compressed. So if you don't want the
2560 text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
2561 Because tEXt and zTXt chunks don't have a language field, if you
2562 specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
2563 any language code or translated keyword will not be written out.
2565 Until text gets around 1000 bytes, it is not worth compressing it.
2566 After the text has been written out to the file, the compression type
2567 is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2568 so that it isn't written out again at the end (in case you are calling
2569 png_write_end() with the same struct.
2571 The keywords that are given in the PNG Specification are:
2573 Title Short (one line) title or
2575 Author Name of image's creator
2576 Description Description of image (possibly long)
2577 Copyright Copyright notice
2578 Creation Time Time of original image creation
2579 (usually RFC 1123 format, see below)
2580 Software Software used to create the image
2581 Disclaimer Legal disclaimer
2582 Warning Warning of nature of content
2583 Source Device used to create the image
2584 Comment Miscellaneous comment; conversion
2585 from other image format
2587 The keyword-text pairs work like this. Keywords should be short
2588 simple descriptions of what the comment is about. Some typical
2589 keywords are found in the PNG specification, as is some recommendations
2590 on keywords. You can repeat keywords in a file. You can even write
2591 some text before the image and some after. For example, you may want
2592 to put a description of the image before the image, but leave the
2593 disclaimer until after, so viewers working over modem connections
2594 don't have to wait for the disclaimer to go over the modem before
2595 they start seeing the image. Finally, keywords should be full
2596 words, not abbreviations. Keywords and text are in the ISO 8859-1
2597 (Latin-1) character set (a superset of regular ASCII) and can not
2598 contain NUL characters, and should not contain control or other
2599 unprintable characters. To make the comments widely readable, stick
2600 with basic ASCII, and avoid machine specific character set extensions
2601 like the IBM-PC character set. The keyword must be present, but
2602 you can leave off the text string on non-compressed pairs.
2603 Compressed pairs must have a text string, as only the text string
2604 is compressed anyway, so the compression would be meaningless.
2606 PNG supports modification time via the png_time structure. Two
2607 conversion routines are provided, png_convert_from_time_t() for
2608 time_t and png_convert_from_struct_tm() for struct tm. The
2609 time_t routine uses gmtime(). You don't have to use either of
2610 these, but if you wish to fill in the png_time structure directly,
2611 you should provide the time in universal time (GMT) if possible
2612 instead of your local time. Note that the year number is the full
2613 year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
2614 that months start with 1.
2616 If you want to store the time of the original image creation, you should
2617 use a plain tEXt chunk with the "Creation Time" keyword. This is
2618 necessary because the "creation time" of a PNG image is somewhat vague,
2619 depending on whether you mean the PNG file, the time the image was
2620 created in a non-PNG format, a still photo from which the image was
2621 scanned, or possibly the subject matter itself. In order to facilitate
2622 machine-readable dates, it is recommended that the "Creation Time"
2623 tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
2624 although this isn't a requirement. Unlike the tIME chunk, the
2625 "Creation Time" tEXt chunk is not expected to be automatically changed
2626 by the software. To facilitate the use of RFC 1123 dates, a function
2627 png_convert_to_rfc1123(png_timep) is provided to convert from PNG
2628 time to an RFC 1123 format string.
2630 .SS Writing unknown chunks
2632 You can use the png_set_unknown_chunks function to queue up chunks
2633 for writing. You give it a chunk name, raw data, and a size; that's
2634 all there is to it. The chunks will be written by the next following
2635 png_write_info_before_PLTE, png_write_info, or png_write_end function.
2636 Any chunks previously read into the info structure's unknown-chunk
2637 list will also be written out in a sequence that satisfies the PNG
2638 specification's ordering rules.
2640 .SS The high-level write interface
2642 At this point there are two ways to proceed; through the high-level
2643 write interface, or through a sequence of low-level write operations.
2644 You can use the high-level interface if your image data is present
2645 in the info structure. All defined output
2646 transformations are permitted, enabled by the following masks.
2648 PNG_TRANSFORM_IDENTITY No transformation
2649 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
2650 PNG_TRANSFORM_PACKSWAP Change order of packed pixels to LSB first
2651 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
2652 PNG_TRANSFORM_SHIFT Normalize pixels to the sBIT depth
2653 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA to BGRA
2654 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA to AG
2655 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity to transparency
2656 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
2657 PNG_TRANSFORM_STRIP_FILLER Strip out filler bytes.
2659 If you have valid image data in the info structure (you can use
2660 png_set_rows() to put image data in the info structure), simply do this:
2662 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
2664 where png_transforms is an integer containing the logical OR of some set of
2665 transformation flags. This call is equivalent to png_write_info(),
2666 followed the set of transformations indicated by the transform mask,
2667 then png_write_image(), and finally png_write_end().
2669 (The final parameter of this call is not yet used. Someday it might point
2670 to transformation parameters required by some future output transform.)
2672 .SS The low-level write interface
2674 If you are going the low-level route instead, you are now ready to
2675 write all the file information up to the actual image data. You do
2676 this with a call to png_write_info().
2678 png_write_info(png_ptr, info_ptr);
2680 Note that there is one transformation you may need to do before
2681 png_write_info(). In PNG files, the alpha channel in an image is the
2682 level of opacity. If your data is supplied as a level of
2683 transparency, you can invert the alpha channel before you write it, so
2684 that 0 is fully transparent and 255 (in 8-bit or paletted images) or
2685 65535 (in 16-bit images) is fully opaque, with
2687 png_set_invert_alpha(png_ptr);
2689 This must appear before png_write_info() instead of later with the
2690 other transformations because in the case of paletted images the tRNS
2691 chunk data has to be inverted before the tRNS chunk is written. If
2692 your image is not a paletted image, the tRNS data (which in such cases
2693 represents a single color to be rendered as transparent) won't need to
2694 be changed, and you can safely do this transformation after your
2695 png_write_info() call.
2697 If you need to write a private chunk that you want to appear before
2698 the PLTE chunk when PLTE is present, you can write the PNG info in
2699 two steps, and insert code to write your own chunk between them:
2701 png_write_info_before_PLTE(png_ptr, info_ptr);
2702 png_set_unknown_chunks(png_ptr, info_ptr, ...);
2703 png_write_info(png_ptr, info_ptr);
2705 After you've written the file information, you can set up the library
2706 to handle any special transformations of the image data. The various
2707 ways to transform the data will be described in the order that they
2708 should occur. This is important, as some of these change the color
2709 type and/or bit depth of the data, and some others only work on
2710 certain color types and bit depths. Even though each transformation
2711 checks to see if it has data that it can do something with, you should
2712 make sure to only enable a transformation if it will be valid for the
2713 data. For example, don't swap red and blue on grayscale data.
2715 PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
2716 the library to strip input data that has 4 or 8 bytes per pixel down
2717 to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
2720 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
2722 where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
2723 PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
2724 is stored XRGB or RGBX.
2726 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2727 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
2728 If the data is supplied at 1 pixel per byte, use this code, which will
2729 correctly pack the pixels into a single byte:
2731 png_set_packing(png_ptr);
2733 PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
2734 data is of another bit depth, you can write an sBIT chunk into the
2735 file so that decoders can recover the original data if desired.
2737 /* Set the true bit depth of the image data */
2738 if (color_type & PNG_COLOR_MASK_COLOR)
2740 sig_bit.red = true_bit_depth;
2741 sig_bit.green = true_bit_depth;
2742 sig_bit.blue = true_bit_depth;
2746 sig_bit.gray = true_bit_depth;
2748 if (color_type & PNG_COLOR_MASK_ALPHA)
2750 sig_bit.alpha = true_bit_depth;
2753 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
2755 If the data is stored in the row buffer in a bit depth other than
2756 one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
2757 this will scale the values to appear to be the correct bit depth as
2760 png_set_shift(png_ptr, &sig_bit);
2762 PNG files store 16 bit pixels in network byte order (big-endian,
2763 ie. most significant bits first). This code would be used if they are
2764 supplied the other way (little-endian, i.e. least significant bits
2765 first, the way PCs store them):
2768 png_set_swap(png_ptr);
2770 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2771 need to change the order the pixels are packed into bytes, you can use:
2774 png_set_packswap(png_ptr);
2776 PNG files store 3 color pixels in red, green, blue order. This code
2777 would be used if they are supplied as blue, green, red:
2779 png_set_bgr(png_ptr);
2781 PNG files describe monochrome as black being zero and white being
2782 one. This code would be used if the pixels are supplied with this reversed
2783 (black being one and white being zero):
2785 png_set_invert_mono(png_ptr);
2787 Finally, you can write your own transformation function if none of
2788 the existing ones meets your needs. This is done by setting a callback
2791 png_set_write_user_transform_fn(png_ptr,
2792 write_transform_fn);
2794 You must supply the function
2796 void write_transform_fn(png_ptr ptr, row_info_ptr
2797 row_info, png_bytep data)
2799 See pngtest.c for a working example. Your function will be called
2800 before any of the other transformations are processed.
2802 You can also set up a pointer to a user structure for use by your
2805 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
2807 The user_channels and user_depth parameters of this function are ignored
2808 when writing; you can set them to zero as shown.
2810 You can retrieve the pointer via the function png_get_user_transform_ptr().
2813 voidp write_user_transform_ptr =
2814 png_get_user_transform_ptr(png_ptr);
2816 It is possible to have libpng flush any pending output, either manually,
2817 or automatically after a certain number of lines have been written. To
2818 flush the output stream a single time call:
2820 png_write_flush(png_ptr);
2822 and to have libpng flush the output stream periodically after a certain
2823 number of scanlines have been written, call:
2825 png_set_flush(png_ptr, nrows);
2827 Note that the distance between rows is from the last time png_write_flush()
2828 was called, or the first row of the image if it has never been called.
2829 So if you write 50 lines, and then png_set_flush 25, it will flush the
2830 output on the next scanline, and every 25 lines thereafter, unless
2831 png_write_flush() is called before 25 more lines have been written.
2832 If nrows is too small (less than about 10 lines for a 640 pixel wide
2833 RGB image) the image compression may decrease noticeably (although this
2834 may be acceptable for real-time applications). Infrequent flushing will
2835 only degrade the compression performance by a few percent over images
2836 that do not use flushing.
2838 .SS Writing the image data
2840 That's it for the transformations. Now you can write the image data.
2841 The simplest way to do this is in one function call. If you have the
2842 whole image in memory, you can just call png_write_image() and libpng
2843 will write the image. You will need to pass in an array of pointers to
2844 each row. This function automatically handles interlacing, so you don't
2845 need to call png_set_interlace_handling() or call this function multiple
2846 times, or any of that other stuff necessary with png_write_rows().
2848 png_write_image(png_ptr, row_pointers);
2850 where row_pointers is:
2852 png_byte *row_pointers[height];
2854 You can point to void or char or whatever you use for pixels.
2856 If you don't want to write the whole image at once, you can
2857 use png_write_rows() instead. If the file is not interlaced,
2860 png_write_rows(png_ptr, row_pointers,
2863 row_pointers is the same as in the png_write_image() call.
2865 If you are just writing one row at a time, you can do this with
2866 a single row_pointer instead of an array of row_pointers:
2868 png_bytep row_pointer = row;
2870 png_write_row(png_ptr, row_pointer);
2872 When the file is interlaced, things can get a good deal more
2873 complicated. The only currently (as of the PNG Specification
2874 version 1.2, dated July 1999) defined interlacing scheme for PNG files
2875 is the "Adam7" interlace scheme, that breaks down an
2876 image into seven smaller images of varying size. libpng will build
2877 these images for you, or you can do them yourself. If you want to
2878 build them yourself, see the PNG specification for details of which
2879 pixels to write when.
2881 If you don't want libpng to handle the interlacing details, just
2882 use png_set_interlace_handling() and call png_write_rows() the
2883 correct number of times to write all seven sub-images.
2885 If you want libpng to build the sub-images, call this before you start
2889 png_set_interlace_handling(png_ptr);
2891 This will return the number of passes needed. Currently, this
2892 is seven, but may change if another interlace type is added.
2894 Then write the complete image number_of_passes times.
2896 png_write_rows(png_ptr, row_pointers,
2899 As some of these rows are not used, and thus return immediately,
2900 you may want to read about interlacing in the PNG specification,
2901 and only update the rows that are actually used.
2903 .SS Finishing a sequential write
2905 After you are finished writing the image, you should finish writing
2906 the file. If you are interested in writing comments or time, you should
2907 pass an appropriately filled png_info pointer. If you are not interested,
2910 png_write_end(png_ptr, info_ptr);
2912 When you are done, you can free all memory used by libpng like this:
2914 png_destroy_write_struct(&png_ptr, &info_ptr);
2916 It is also possible to individually free the info_ptr members that
2917 point to libpng-allocated storage with the following function:
2919 png_free_data(png_ptr, info_ptr, mask, n)
2920 mask - identifies data to be freed, a mask
2921 containing the logical OR of one or
2923 PNG_FREE_PLTE, PNG_FREE_TRNS,
2924 PNG_FREE_HIST, PNG_FREE_ICCP,
2925 PNG_FREE_PCAL, PNG_FREE_ROWS,
2926 PNG_FREE_SCAL, PNG_FREE_SPLT,
2927 PNG_FREE_TEXT, PNG_FREE_UNKN,
2928 or simply PNG_FREE_ALL
2929 n - sequence number of item to be freed
2932 This function may be safely called when the relevant storage has
2933 already been freed, or has not yet been allocated, or was allocated
2934 by the user and not by libpng, and will in those
2935 cases do nothing. The "n" parameter is ignored if only one item
2936 of the selected data type, such as PLTE, is allowed. If "n" is not
2937 -1, and multiple items are allowed for the data type identified in
2938 the mask, such as text or sPLT, only the n'th item is freed.
2940 If you allocated data such as a palette that you passed
2941 in to libpng with png_set_*, you must not free it until just before the call to
2942 png_destroy_write_struct().
2944 The default behavior is only to free data that was allocated internally
2945 by libpng. This can be changed, so that libpng will not free the data,
2946 or so that it will free data that was allocated by the user with png_malloc()
2947 or png_zalloc() and passed in via a png_set_*() function, with
2949 png_data_freer(png_ptr, info_ptr, freer, mask)
2950 mask - which data elements are affected
2951 same choices as in png_free_data()
2953 PNG_DESTROY_WILL_FREE_DATA
2954 PNG_SET_WILL_FREE_DATA
2955 PNG_USER_WILL_FREE_DATA
2957 For example, to transfer responsibility for some data from a read structure
2958 to a write structure, you could use
2960 png_data_freer(read_ptr, read_info_ptr,
2961 PNG_USER_WILL_FREE_DATA,
2962 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2963 png_data_freer(write_ptr, write_info_ptr,
2964 PNG_DESTROY_WILL_FREE_DATA,
2965 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2967 thereby briefly reassigning responsibility for freeing to the user but
2968 immediately afterwards reassigning it once more to the write_destroy
2969 function. Having done this, it would then be safe to destroy the read
2970 structure and continue to use the PLTE, tRNS, and hIST data in the write
2973 This function only affects data that has already been allocated.
2974 You can call this function before calling after the png_set_*() functions
2975 to control whether the user or png_destroy_*() is supposed to free the data.
2976 When the user assumes responsibility for libpng-allocated data, the
2977 application must use
2978 png_free() to free it, and when the user transfers responsibility to libpng
2979 for data that the user has allocated, the user must have used png_malloc()
2980 or png_zalloc() to allocate it.
2982 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2983 separately, do not transfer responsibility for freeing text_ptr to libpng,
2984 because when libpng fills a png_text structure it combines these members with
2985 the key member, and png_free_data() will free only text_ptr.key. Similarly,
2986 if you transfer responsibility for free'ing text_ptr from libpng to your
2987 application, your application must not separately free those members.
2988 For a more compact example of writing a PNG image, see the file example.c.
2990 .SH V. Modifying/Customizing libpng:
2992 There are three issues here. The first is changing how libpng does
2993 standard things like memory allocation, input/output, and error handling.
2994 The second deals with more complicated things like adding new chunks,
2995 adding new transformations, and generally changing how libpng works.
2996 Both of those are compile-time issues; that is, they are generally
2997 determined at the time the code is written, and there is rarely a need
2998 to provide the user with a means of changing them. The third is a
2999 run-time issue: choosing between and/or tuning one or more alternate
3000 versions of computationally intensive routines; specifically, optimized
3001 assembly-language (and therefore compiler- and platform-dependent)
3004 Memory allocation, input/output, and error handling
3006 All of the memory allocation, input/output, and error handling in libpng
3007 goes through callbacks that are user-settable. The default routines are
3008 in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
3009 these functions, call the appropriate png_set_*_fn() function.
3011 Memory allocation is done through the functions png_malloc(), png_zalloc(),
3012 and png_free(). These currently just call the standard C functions. If
3013 your pointers can't access more then 64K at a time, you will want to set
3014 MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling
3015 memory allocation on a platform will change between applications, these
3016 functions must be modified in the library at compile time. If you prefer
3017 to use a different method of allocating and freeing data, you can use
3019 png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr, png_malloc_ptr
3020 malloc_fn, png_free_ptr free_fn)
3022 This function also provides a void pointer that can be retrieved via
3024 mem_ptr=png_get_mem_ptr(png_ptr);
3026 Your replacement memory functions must have prototypes as follows:
3028 png_voidp malloc_fn(png_structp png_ptr, png_uint_32 size);
3029 void free_fn(png_structp png_ptr, png_voidp ptr);
3031 Input/Output in libpng is done through png_read() and png_write(),
3032 which currently just call fread() and fwrite(). The FILE * is stored in
3033 png_struct and is initialized via png_init_io(). If you wish to change
3034 the method of I/O, the library supplies callbacks that you can set
3035 through the function png_set_read_fn() and png_set_write_fn() at run
3036 time, instead of calling the png_init_io() function. These functions
3037 also provide a void pointer that can be retrieved via the function
3038 png_get_io_ptr(). For example:
3040 png_set_read_fn(png_structp read_ptr,
3041 voidp read_io_ptr, png_rw_ptr read_data_fn)
3043 png_set_write_fn(png_structp write_ptr,
3044 voidp write_io_ptr, png_rw_ptr write_data_fn,
3045 png_flush_ptr output_flush_fn);
3047 voidp read_io_ptr = png_get_io_ptr(read_ptr);
3048 voidp write_io_ptr = png_get_io_ptr(write_ptr);
3050 The replacement I/O functions must have prototypes as follows:
3052 void user_read_data(png_structp png_ptr,
3053 png_bytep data, png_uint_32 length);
3054 void user_write_data(png_structp png_ptr,
3055 png_bytep data, png_uint_32 length);
3056 void user_flush_data(png_structp png_ptr);
3058 Supplying NULL for the read, write, or flush functions sets them back
3059 to using the default C stream functions. It is an error to read from
3060 a write stream, and vice versa.
3062 Error handling in libpng is done through png_error() and png_warning().
3063 Errors handled through png_error() are fatal, meaning that png_error()
3064 should never return to its caller. Currently, this is handled via
3065 setjmp() and longjmp() (unless you have compiled libpng with
3066 PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
3067 but you could change this to do things like exit() if you should wish.
3069 On non-fatal errors, png_warning() is called
3070 to print a warning message, and then control returns to the calling code.
3071 By default png_error() and png_warning() print a message on stderr via
3072 fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
3073 (because you don't want the messages) or PNG_NO_STDIO defined (because
3074 fprintf() isn't available). If you wish to change the behavior of the error
3075 functions, you will need to set up your own message callbacks. These
3076 functions are normally supplied at the time that the png_struct is created.
3077 It is also possible to redirect errors and warnings to your own replacement
3078 functions after png_create_*_struct() has been called by calling:
3080 png_set_error_fn(png_structp png_ptr,
3081 png_voidp error_ptr, png_error_ptr error_fn,
3082 png_error_ptr warning_fn);
3084 png_voidp error_ptr = png_get_error_ptr(png_ptr);
3086 If NULL is supplied for either error_fn or warning_fn, then the libpng
3087 default function will be used, calling fprintf() and/or longjmp() if a
3088 problem is encountered. The replacement error functions should have
3089 parameters as follows:
3091 void user_error_fn(png_structp png_ptr,
3092 png_const_charp error_msg);
3093 void user_warning_fn(png_structp png_ptr,
3094 png_const_charp warning_msg);
3096 The motivation behind using setjmp() and longjmp() is the C++ throw and
3097 catch exception handling methods. This makes the code much easier to write,
3098 as there is no need to check every return code of every function call.
3099 However, there are some uncertainties about the status of local variables
3100 after a longjmp, so the user may want to be careful about doing anything after
3101 setjmp returns non-zero besides returning itself. Consult your compiler
3102 documentation for more details. For an alternative approach, you may wish
3103 to use the "cexcept" facility (see http://cexcept.sourceforge.net).
3107 If you need to read or write custom chunks, you may need to get deeper
3108 into the libpng code. The library now has mechanisms for storing
3109 and writing chunks of unknown type; you can even declare callbacks
3110 for custom chunks. Hoewver, this may not be good enough if the
3111 library code itself needs to know about interactions between your
3112 chunk and existing `intrinsic' chunks.
3114 If you need to write a new intrinsic chunk, first read the PNG
3115 specification. Acquire a first level of
3116 understanding of how it works. Pay particular attention to the
3117 sections that describe chunk names, and look at how other chunks were
3118 designed, so you can do things similarly. Second, check out the
3119 sections of libpng that read and write chunks. Try to find a chunk
3120 that is similar to yours and use it as a template. More details can
3121 be found in the comments inside the code. It is best to handle unknown
3122 chunks in a generic method, via callback functions, instead of by
3123 modifying libpng functions.
3125 If you wish to write your own transformation for the data, look through
3126 the part of the code that does the transformations, and check out some of
3127 the simpler ones to get an idea of how they work. Try to find a similar
3128 transformation to the one you want to add and copy off of it. More details
3129 can be found in the comments inside the code itself.
3131 .SS Configuring for 16 bit platforms
3133 You will want to look into zconf.h to tell zlib (and thus libpng) that
3134 it cannot allocate more then 64K at a time. Even if you can, the memory
3135 won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
3137 .SS Configuring for DOS
3139 For DOS users who only have access to the lower 640K, you will
3140 have to limit zlib's memory usage via a png_set_compression_mem_level()
3141 call. See zlib.h or zconf.h in the zlib library for more information.
3143 .SS Configuring for Medium Model
3145 Libpng's support for medium model has been tested on most of the popular
3146 compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
3147 defined, and FAR gets defined to far in pngconf.h, and you should be
3148 all set. Everything in the library (except for zlib's structure) is
3149 expecting far data. You must use the typedefs with the p or pp on
3150 the end for pointers (or at least look at them and be careful). Make
3151 note that the rows of data are defined as png_bytepp, which is an
3152 unsigned char far * far *.
3154 .SS Configuring for gui/windowing platforms:
3156 You will need to write new error and warning functions that use the GUI
3157 interface, as described previously, and set them to be the error and
3158 warning functions at the time that png_create_*_struct() is called,
3159 in order to have them available during the structure initialization.
3160 They can be changed later via png_set_error_fn(). On some compilers,
3161 you may also have to change the memory allocators (png_malloc, etc.).
3163 .SS Configuring for compiler xxx:
3165 All includes for libpng are in pngconf.h. If you need to add/change/delete
3166 an include, this is the place to do it. The includes that are not
3167 needed outside libpng are protected by the PNG_INTERNAL definition,
3168 which is only defined for those routines inside libpng itself. The
3169 files in libpng proper only include png.h, which includes pngconf.h.
3171 .SS Configuring zlib:
3173 There are special functions to configure the compression. Perhaps the
3174 most useful one changes the compression level, which currently uses
3175 input compression values in the range 0 - 9. The library normally
3176 uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
3177 have shown that for a large majority of images, compression values in
3178 the range 3-6 compress nearly as well as higher levels, and do so much
3179 faster. For online applications it may be desirable to have maximum speed
3180 (Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
3181 specify no compression (Z_NO_COMPRESSION = 0), but this would create
3182 files larger than just storing the raw bitmap. You can specify the
3183 compression level by calling:
3185 png_set_compression_level(png_ptr, level);
3187 Another useful one is to reduce the memory level used by the library.
3188 The memory level defaults to 8, but it can be lowered if you are
3189 short on memory (running DOS, for example, where you only have 640K).
3191 png_set_compression_mem_level(png_ptr, level);
3193 The other functions are for configuring zlib. They are not recommended
3194 for normal use and may result in writing an invalid PNG file. See
3195 zlib.h for more information on what these mean.
3197 png_set_compression_strategy(png_ptr,
3199 png_set_compression_window_bits(png_ptr,
3201 png_set_compression_method(png_ptr, method);
3202 png_set_compression_buffer_size(png_ptr, size);
3204 .SS Controlling row filtering
3206 If you want to control whether libpng uses filtering or not, which
3207 filters are used, and how it goes about picking row filters, you
3208 can call one of these functions. The selection and configuration
3209 of row filters can have a significant impact on the size and
3210 encoding speed and a somewhat lesser impact on the decoding speed
3211 of an image. Filtering is enabled by default for RGB and grayscale
3212 images (with and without alpha), but not for paletted images nor
3213 for any images with bit depths less than 8 bits/pixel.
3215 The 'method' parameter sets the main filtering method, which is
3216 currently only '0' in the PNG 1.2 specification. The 'filters'
3217 parameter sets which filter(s), if any, should be used for each
3218 scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
3219 to turn filtering on and off, respectively.
3221 Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
3222 PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
3223 ORed together with '|' to specify one or more filters to use.
3224 These filters are described in more detail in the PNG specification. If
3225 you intend to change the filter type during the course of writing
3226 the image, you should start with flags set for all of the filters
3227 you intend to use so that libpng can initialize its internal
3228 structures appropriately for all of the filter types.
3230 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
3231 PNG_FILTER_UP | PNG_FILTER_AVE |
3232 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
3234 filters = one of PNG_FILTER_VALUE_NONE,
3235 PNG_FILTER_VALUE_SUB, PNG_FILTER_VALUE_UP,
3236 PNG_FILTER_VALUE_AVE, PNG_FILTER_VALUE_PAETH
3238 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3240 The second parameter can also be PNG_INTRAPIXEL_DIFFERENCING
3241 if you are writing a PNG to be embedded in a MNG
3242 datastream. This parameter must be the same as the
3243 value of filter_method used in png_set_IHDR().
3245 It is also possible to influence how libpng chooses from among the
3246 available filters. This is done in two ways - by telling it how
3247 important it is to keep the same filter for successive rows, and
3248 by telling it the relative computational costs of the filters.
3250 double weights[3] = {1.5, 1.3, 1.1},
3251 costs[PNG_FILTER_VALUE_LAST] =
3252 {1.0, 1.3, 1.3, 1.5, 1.7};
3254 png_set_filter_selection(png_ptr,
3255 PNG_FILTER_SELECTION_WEIGHTED, 3,
3258 The weights are multiplying factors that indicate to libpng that the
3259 row filter should be the same for successive rows unless another row filter
3260 is that many times better than the previous filter. In the above example,
3261 if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
3262 "sum of absolute differences" 1.5 x 1.3 times higher than other filters
3263 and still be chosen, while the NONE filter could have a sum 1.1 times
3264 higher than other filters and still be chosen. Unspecified weights are
3265 taken to be 1.0, and the specified weights should probably be declining
3266 like those above in order to emphasize recent filters over older filters.
3268 The filter costs specify for each filter type a relative decoding cost
3269 to be considered when selecting row filters. This means that filters
3270 with higher costs are less likely to be chosen over filters with lower
3271 costs, unless their "sum of absolute differences" is that much smaller.
3272 The costs do not necessarily reflect the exact computational speeds of
3273 the various filters, since this would unduly influence the final image
3276 Note that the numbers above were invented purely for this example and
3277 are given only to help explain the function usage. Little testing has
3278 been done to find optimum values for either the costs or the weights.
3280 .SS Removing unwanted object code
3282 There are a bunch of #define's in pngconf.h that control what parts of
3283 libpng are compiled. All the defines end in _SUPPORTED. If you are
3284 never going to use a capability, you can change the #define to #undef
3285 before recompiling libpng and save yourself code and data space, or
3286 you can turn off individual capabilities with defines that begin with
3289 You can also turn all of the transforms and ancillary chunk capabilities
3290 off en masse with compiler directives that define
3291 PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
3293 along with directives to turn on any of the capabilities that you do
3294 want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
3295 the extra transformations but still leave the library fully capable of reading
3296 and writing PNG files with all known public chunks
3297 Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
3298 produces a library that is incapable of reading or writing ancillary chunks.
3299 If you are not using the progressive reading capability, you can
3300 turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
3301 this with the INTERLACING capability, which you'll still have).
3303 All the reading and writing specific code are in separate files, so the
3304 linker should only grab the files it needs. However, if you want to
3305 make sure, or if you are building a stand alone library, all the
3306 reading files start with pngr and all the writing files start with
3307 pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
3308 are used for both reading and writing, and always need to be included.
3309 The progressive reader is in pngpread.c
3311 If you are creating or distributing a dynamically linked library (a .so
3312 or DLL file), you should not remove or disable any parts of the library,
3313 as this will cause applications linked with different versions of the
3314 library to fail if they call functions not available in your library.
3315 The size of the library itself should not be an issue, because only
3316 those sections that are actually used will be loaded into memory.
3318 .SS Requesting debug printout
3320 The macro definition PNG_DEBUG can be used to request debugging
3321 printout. Set it to an integer value in the range 0 to 3. Higher
3322 numbers result in increasing amounts of debugging information. The
3323 information is printed to the "stderr" file, unless another file
3324 name is specified in the PNG_DEBUG_FILE macro definition.
3326 When PNG_DEBUG > 0, the following functions (macros) become available:
3328 png_debug(level, message)
3329 png_debug1(level, message, p1)
3330 png_debug2(level, message, p1, p2)
3332 in which "level" is compared to PNG_DEBUG to decide whether to print
3333 the message, "message" is the formatted string to be printed,
3334 and p1 and p2 are parameters that are to be embedded in the string
3335 according to printf-style formatting directives. For example,
3337 png_debug1(2, "foo=%d\n", foo);
3342 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
3344 When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
3345 can still use PNG_DEBUG to control your own debugging:
3351 When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
3352 having level = 0 will be printed. There aren't any such statements in
3353 this version of libpng, but if you insert some they will be printed.
3358 The MNG specification (available at http://www.libpng.org/pub/mng) allows
3359 certain extensions to PNG for PNG images that are embedded in MNG datastreams.
3360 Libpng can support some of these extensions. To enable them, use the
3361 png_permit_mng_features() function:
3363 feature_set = png_permit_mng_features(png_ptr, mask)
3364 mask is a png_uint_32 containing the logical OR of the
3365 features you want to enable. These include
3366 PNG_FLAG_MNG_EMPTY_PLTE
3367 PNG_FLAG_MNG_FILTER_64
3368 PNG_ALL_MNG_FEATURES
3369 feature_set is a png_32_uint that is the logical AND of
3370 your mask with the set of MNG features that is
3371 supported by the version of libpng that you are using.
3373 It is an error to use this function when reading or writing a standalone
3374 PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
3375 in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
3376 and the MHDR and MEND chunks. Libpng does not provide support for these
3377 or any other MNG chunks; your application must provide its own support for
3378 them. You may wish to consider using libmng (available at
3379 http://www.libmng.com) instead.
3381 .SH VII. Changes to Libpng from version 0.88
3383 It should be noted that versions of libpng later than 0.96 are not
3384 distributed by the original libpng author, Guy Schalnat, nor by
3385 Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
3386 distributed versions 0.89 through 0.96, but rather by another member
3387 of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
3388 still alive and well, but they have moved on to other things.
3390 The old libpng functions png_read_init(), png_write_init(),
3391 png_info_init(), png_read_destroy(), and png_write_destory() have been
3392 moved to PNG_INTERNAL in version 0.95 to discourage their use. These
3393 functions will be removed from libpng version 2.0.0.
3395 The preferred method of creating and initializing the libpng structures is
3396 via the png_create_read_struct(), png_create_write_struct(), and
3397 png_create_info_struct() because they isolate the size of the structures
3398 from the application, allow version error checking, and also allow the
3399 use of custom error handling routines during the initialization, which
3400 the old functions do not. The functions png_read_destroy() and
3401 png_write_destroy() do not actually free the memory that libpng
3402 allocated for these structs, but just reset the data structures, so they
3403 can be used instead of png_destroy_read_struct() and
3404 png_destroy_write_struct() if you feel there is too much system overhead
3405 allocating and freeing the png_struct for each image read.
3407 Setting the error callbacks via png_set_message_fn() before
3408 png_read_init() as was suggested in libpng-0.88 is no longer supported
3409 because this caused applications that do not use custom error functions
3410 to fail if the png_ptr was not initialized to zero. It is still possible
3411 to set the error callbacks AFTER png_read_init(), or to change them with
3412 png_set_error_fn(), which is essentially the same function, but with a new
3413 name to force compilation errors with applications that try to use the old
3416 Starting with version 1.0.7, you can find out which version of the library
3417 you are using at run-time:
3419 png_uint_32 libpng_vn = png_access_version_number();
3421 The number libpng_vn is constructed from the major version, minor
3422 version with leading zero, and release number with leading zero,
3423 (e.g., libpng_vn for version 1.0.7 is 10007).
3425 You can also check which version of png.h you used when compiling your
3428 png_uint_32 application_vn = PNG_LIBPNG_VER;
3430 .SH VIII. Y2K Compliance in libpng
3434 Since the PNG Development group is an ad-hoc body, we can't make
3435 an official declaration.
3437 This is your unofficial assurance that libpng from version 0.71 and
3438 upward through 1.0.9 are Y2K compliant. It is my belief that earlier
3439 versions were also Y2K compliant.
3441 Libpng only has three year fields. One is a 2-byte unsigned integer that
3442 will hold years up to 65535. The other two hold the date in text
3443 format, and will hold years up to 9999.
3446 "png_uint_16 year" in png_time_struct.
3449 "png_charp time_buffer" in png_struct and
3450 "near_time_buffer", which is a local character string in png.c.
3452 There are seven time-related functions:
3454 png_convert_to_rfc_1123() in png.c
3455 (formerly png_convert_to_rfc_1152() in error)
3456 png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c
3457 png_convert_from_time_t() in pngwrite.c
3458 png_get_tIME() in pngget.c
3459 png_handle_tIME() in pngrutil.c, called in pngread.c
3460 png_set_tIME() in pngset.c
3461 png_write_tIME() in pngwutil.c, called in pngwrite.c
3463 All appear to handle dates properly in a Y2K environment. The
3464 png_convert_from_time_t() function calls gmtime() to convert from system
3465 clock time, which returns (year - 1900), which we properly convert to
3466 the full 4-digit year. There is a possibility that applications using
3467 libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
3468 function, or that they are incorrectly passing only a 2-digit year
3469 instead of "year - 1900" into the png_convert_from_struct_tm() function,
3470 but this is not under our control. The libpng documentation has always
3471 stated that it works with 4-digit years, and the APIs have been
3474 The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
3475 integer to hold the year, and can hold years as large as 65535.
3477 zlib, upon which libpng depends, is also Y2K compliant. It contains
3478 no date-related code.
3481 Glenn Randers-Pehrson
3483 PNG Development Group
3487 Note about libpng version numbers:
3489 Due to various miscommunications, unforeseen code incompatibilities
3490 and occasional factors outside the authors' control, version numbering
3491 on the library has not always been consistent and straightforward.
3492 The following table summarizes matters since version 0.89c, which was
3493 the first widely used release:
3495 source png.h png.h shared-lib
3496 version string int version
3497 ------- ------ ----- ----------
3498 0.89c ("1.0 beta 3") 0.89 89 1.0.89
3499 0.90 ("1.0 beta 4") 0.90 90 0.90 [should have been 2.0.90]
3500 0.95 ("1.0 beta 5") 0.95 95 0.95 [should have been 2.0.95]
3501 0.96 ("1.0 beta 6") 0.96 96 0.96 [should have been 2.0.96]
3502 0.97b ("1.00.97 beta 7") 1.00.97 97 1.0.1 [should have been 2.0.97]
3503 0.97c 0.97 97 2.0.97
3506 0.99a-m 0.99 99 2.0.99
3507 1.00 1.00 100 2.1.0 [100 should be 10000]
3508 1.0.0 1.0.0 100 2.1.0 [100 should be 10000]
3509 1.0.1 1.0.1 10001 2.1.0
3510 1.0.1a-e 1.0.1a-e 10002 2.1.0.1a-e
3511 1.0.2 1.0.2 10002 2.1.0.2
3512 1.0.2a-b 1.0.2a-b 10003 2.1.0.2a-b
3513 1.0.3 1.0.3 10003 2.1.0.3
3514 1.0.3a-d 1.0.3a-d 10004 2.1.0.3a-d
3515 1.0.4 1.0.4 10004 2.1.0.4
3516 1.0.4a-f 1.0.4a-f 10005 2.1.0.4a-f
3517 1.0.5 (+ 2 patches) 1.0.5 10005 2.1.0.5
3518 1.0.5a-d 1.0.5a-d 10006 2.1.0.5a-d
3519 1.0.5e-r 1.0.5e-r 10100 2.1.0.5e-r (not compatible)
3520 1.0.5s-v 1.0.5s-v 10006 2.1.0.5s-v (compatible)
3521 1.0.6 (+ 3 patches) 1.0.6 10006 2.1.0.6
3522 1.0.6d 1.0.6d 10007 2.1.0.6d
3523 1.0.7 1.0.7 10007 2.1.0.7 (still compatible)
3525 Henceforth the source version will match the shared-library minor
3526 and patch numbers; the shared-library major version number will be
3527 used for changes in backward compatibility, as it is intended. The
3528 PNG_PNGLIB_VER macro, which is not used within libpng but is available
3529 for applications, is an unsigned integer of the form xyyzz corresponding
3530 to the source version x.y.z (leading zeros in y and z). Beta versions
3531 are given the previous public release number plus a letter or two.
3538 ftp://ftp.uu.net/graphics/png
3539 http://www.libpng.org/pub/png
3544 (generally) at the same location as
3548 ftp://ftp.uu.net/pub/archiving/zip/zlib
3550 ftp://ftp.info-zip.org/pub/infozip/zlib
3553 .IR PNG specification: RFC 2083
3555 (generally) at the same location as
3559 ftp://ds.internic.net/rfc/rfc2083.txt
3561 or (as a W3C Recommendation) at
3563 http://www.w3.org/TR/REC-png.html
3566 In the case of any inconsistency between the PNG specification
3567 and this library, the specification takes precedence.
3570 This man page: Glenn Randers-Pehrson
3571 <randeg@alum.rpi.edu>
3573 The contributing authors would like to thank all those who helped
3574 with testing, bug fixes, and patience. This wouldn't have been
3575 possible without all of you.
3577 Thanks to Frank J. T. Wojcik for helping with the documentation.
3579 Libpng version 1.0.9 - January 31, 2001:
3580 Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
3581 Currently maintained by Glenn Randers-Pehrson (randeg@alum.rpi.edu).
3583 Supported by the PNG development group
3585 (png-implement@ccrc.wustl.edu).
3587 .SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
3589 (This copy of the libpng notices is provided for your convenience. In case of
3590 any discrepancy between this copy and the notices in the file png.h that is
3591 included in the libpng distribution, the latter shall prevail.)
3593 If you modify libpng you may insert additional notices immediately following
3596 libpng versions 1.0.7, July 1, 2000, through 1.0.9, January 31, 2001, are
3597 Copyright (c) 2000 Glenn Randers-Pehrson, and are
3598 distributed according to the same disclaimer and license as libpng-1.0.6
3599 with the following individuals added to the list of Contributing Authors
3601 Simon-Pierre Cadieux
3605 and with the following additions to the disclaimer:
3607 There is no warranty against interference with your enjoyment of the
3608 library or against infringement. There is no warranty that our
3609 efforts or the library will fulfill any of your particular purposes
3610 or needs. This library is provided with all faults, and the entire
3611 risk of satisfactory quality, performance, accuracy, and effort is with
3614 libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
3615 Copyright (c) 1998, 1999 Glenn Randers-Pehrson
3616 Distributed according to the same disclaimer and license as libpng-0.96,
3617 with the following individuals added to the list of Contributing Authors:
3620 Glenn Randers-Pehrson
3623 libpng versions 0.89, June 1996, through 0.96, May 1997, are
3624 Copyright (c) 1996, 1997 Andreas Dilger
3625 Distributed according to the same disclaimer and license as libpng-0.88,
3626 with the following individuals added to the list of Contributing Authors:
3635 libpng versions 0.5, May 1995, through 0.88, January 1996, are
3636 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
3638 For the purposes of this copyright and license, "Contributing Authors"
3639 is defined as the following set of individuals:
3647 The PNG Reference Library is supplied "AS IS". The Contributing Authors
3648 and Group 42, Inc. disclaim all warranties, expressed or implied,
3649 including, without limitation, the warranties of merchantability and of
3650 fitness for any purpose. The Contributing Authors and Group 42, Inc.
3651 assume no liability for direct, indirect, incidental, special, exemplary,
3652 or consequential damages, which may result from the use of the PNG
3653 Reference Library, even if advised of the possibility of such damage.
3655 Permission is hereby granted to use, copy, modify, and distribute this
3656 source code, or portions hereof, for any purpose, without fee, subject
3657 to the following restrictions:
3659 1. The origin of this source code must not be misrepresented.
3661 2. Altered versions must be plainly marked as such and must not
3662 be misrepresented as being the original source.
3664 3. This Copyright notice may not be removed or altered from any
3665 source or altered source distribution.
3667 The Contributing Authors and Group 42, Inc. specifically permit, without
3668 fee, and encourage the use of this source code as a component to
3669 supporting the PNG file format in commercial products. If you use this
3670 source code in a product, acknowledgment is not required but would be
3674 A "png_get_copyright" function is available, for convenient use in "about"
3677 printf("%s",png_get_copyright(NULL));
3679 Also, the PNG logo (in PNG format, of course) is supplied in the
3680 files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
3682 Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a
3683 certification mark of the Open Source Initiative.
3685 Glenn Randers-Pehrson
projects / rrdtool.git / blob