界面编程

开发平台：

Visual C++

libpng.3：源码内容

.TH LIBPNG 3 "December 18, 2008"
.SH NAME
libpng - Portable Network Graphics (PNG) Reference Library 1.2.34
.SH SYNOPSIS
fIfB
fB#include <png.h>fP
fIfB
fBpng_uint_32 png_access_version_number fI(voidfPfB);fP
fIfB
fBint png_check_sig (png_bytep fPfIsigfPfB, int fInumfPfB);fP
fIfB
fBvoid png_chunk_error (png_structp fPfIpng_ptrfPfB, png_const_charp fIerrorfPfB);fP
fIfB
fBvoid png_chunk_warning (png_structp fPfIpng_ptrfPfB, png_const_charp fImessagefPfB);fP
fIfB
fBvoid png_convert_from_struct_tm (png_timep fPfIptimefPfB, struct tm FAR * fIttimefPfB);fP
fIfB
fBvoid png_convert_from_time_t (png_timep fPfIptimefPfB, time_t fIttimefPfB);fP
fIfB
fBpng_charp png_convert_to_rfc1123 (png_structp fPfIpng_ptrfPfB, png_timep fIptimefPfB);fP
fIfB
fBpng_infop png_create_info_struct (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_structp png_create_read_struct (png_const_charp fPfIuser_png_verfPfB, png_voidp fPfIerror_ptrfPfB, png_error_ptr fPfIerror_fnfPfB, png_error_ptr fIwarn_fnfPfB);fP
fIfB
fBpng_structp png_create_read_struct_2(png_const_charp fPfIuser_png_verfPfB, png_voidp fPfIerror_ptrfPfB, png_error_ptr fPfIerror_fnfPfB, png_error_ptr fPfIwarn_fnfPfB, png_voidp fPfImem_ptrfPfB, png_malloc_ptr fPfImalloc_fnfPfB, png_free_ptr fIfree_fnfPfB);fP
fIfB
fBpng_structp png_create_write_struct (png_const_charp fPfIuser_png_verfPfB, png_voidp fPfIerror_ptrfPfB, png_error_ptr fPfIerror_fnfPfB, png_error_ptr fIwarn_fnfPfB);fP
fIfB
fBpng_structp png_create_write_struct_2(png_const_charp fPfIuser_png_verfPfB, png_voidp fPfIerror_ptrfPfB, png_error_ptr fPfIerror_fnfPfB, png_error_ptr fPfIwarn_fnfPfB, png_voidp fPfImem_ptrfPfB, png_malloc_ptr fPfImalloc_fnfPfB, png_free_ptr fIfree_fnfPfB);fP
fIfB
fBint png_debug(int fPfIlevelfPfB, png_const_charp fImessagefPfB);fP
fIfB
fBint png_debug1(int fPfIlevelfPfB, png_const_charp fPfImessagefPfB, fIp1fPfB);fP
fIfB
fBint png_debug2(int fPfIlevelfPfB, png_const_charp fPfImessagefPfB, fPfIp1fPfB, fIp2fPfB);fP
fIfB
fBvoid png_destroy_info_struct (png_structp fPfIpng_ptrfPfB, png_infopp fIinfo_ptr_ptrfPfB);fP
fIfB
fBvoid png_destroy_read_struct (png_structpp fPfIpng_ptr_ptrfPfB, png_infopp fPfIinfo_ptr_ptrfPfB, png_infopp fIend_info_ptr_ptrfPfB);fP
fIfB
fBvoid png_destroy_write_struct (png_structpp fPfIpng_ptr_ptrfPfB, png_infopp fIinfo_ptr_ptrfPfB);fP
fIfB
fBvoid png_error (png_structp fPfIpng_ptrfPfB, png_const_charp fIerrorfPfB);fP
fIfB
fBvoid png_free (png_structp fPfIpng_ptrfPfB, png_voidp fIptrfPfB);fP
fIfB
fBvoid png_free_chunk_list (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_free_default(png_structp fPfIpng_ptrfPfB, png_voidp fIptrfPfB);fP
fIfB
fBvoid png_free_data (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fInumfPfB);fP
fIfB
fBpng_byte png_get_bit_depth (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_bKGD (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_color_16p fI*backgroundfPfB);fP
fIfB
fBpng_byte png_get_channels (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_cHRM (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, double fPfI*white_xfPfB, double fPfI*white_yfPfB, double fPfI*red_xfPfB, double fPfI*red_yfPfB, double fPfI*green_xfPfB, double fPfI*green_yfPfB, double fPfI*blue_xfPfB, double fI*blue_yfPfB);fP
fIfB
fBpng_uint_32 png_get_cHRM_fixed (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfI*white_xfPfB, png_uint_32 fPfI*white_yfPfB, png_uint_32 fPfI*red_xfPfB, png_uint_32 fPfI*red_yfPfB, png_uint_32 fPfI*green_xfPfB, png_uint_32 fPfI*green_yfPfB, png_uint_32 fPfI*blue_xfPfB, png_uint_32 fI*blue_yfPfB);fP
fIfB
fBpng_byte png_get_color_type (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_byte png_get_compression_type (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_byte png_get_copyright (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_voidp png_get_error_ptr (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_byte png_get_filter_type (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_gAMA (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, double fI*file_gammafPfB);fP
fIfB
fBpng_uint_32 png_get_gAMA_fixed (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fI*int_file_gammafPfB);fP
fIfB
fBpng_byte png_get_header_ver (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_byte png_get_header_version (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_hIST (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_16p fI*histfPfB);fP
fIfB
fBpng_uint_32 png_get_iCCP (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_charpp fPfInamefPfB, int fPfI*compression_typefPfB, png_charpp fPfIprofilefPfB, png_uint_32 fI*proflenfPfB);fP
fIfB
fBpng_uint_32 png_get_IHDR (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfI*widthfPfB, png_uint_32 fPfI*heightfPfB, int fPfI*bit_depthfPfB, int fPfI*color_typefPfB, int fPfI*interlace_typefPfB, int fPfI*compression_typefPfB, int fI*filter_typefPfB);fP
fIfB
fBpng_uint_32 png_get_image_height (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_image_width (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fB#if fI!defined(PNG_1_0_X)
fBpng_int_32 png_get_int_32 (png_bytep fIbuffPfB);fP
fIfB#endif
fIfB
fBpng_byte png_get_interlace_type (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_voidp png_get_io_ptr (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_byte png_get_libpng_ver (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_voidp png_get_mem_ptr(png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_oFFs (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfI*offset_xfPfB, png_uint_32 fPfI*offset_yfPfB, int fI*unit_typefPfB);fP
fIfB
fBpng_uint_32 png_get_pCAL (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_charp fPfI*purposefPfB, png_int_32 fPfI*X0fPfB, png_int_32 fPfI*X1fPfB, int fPfI*typefPfB, int fPfI*nparamsfPfB, png_charp fPfI*unitsfPfB, png_charpp fI*paramsfPfB);fP
fIfB
fBpng_uint_32 png_get_pHYs (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfI*res_xfPfB, png_uint_32 fPfI*res_yfPfB, int fI*unit_typefPfB);fP
fIfB
fBfloat png_get_pixel_aspect_ratio (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_pixels_per_meter (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_voidp png_get_progressive_ptr (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_PLTE (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_colorp fPfI*palettefPfB, int fI*num_palettefPfB);fP
fIfB
fBpng_byte png_get_rgb_to_gray_status (png_structp fIpng_ptr)
fBpng_uint_32 png_get_rowbytes (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_bytepp png_get_rows (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_sBIT (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_color_8p fI*sig_bitfPfB);fP
fIfB
fBpng_bytep png_get_signature (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_sPLT (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_spalette_p fI*splt_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_sRGB (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fI*intentfPfB);fP
fIfB
fBpng_uint_32 png_get_text (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_textp fPfI*text_ptrfPfB, int fI*num_textfPfB);fP
fIfB
fBpng_uint_32 png_get_tIME (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_timep fI*mod_timefPfB);fP
fIfB
fBpng_uint_32 png_get_tRNS (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_bytep fPfI*transfPfB, int fPfI*num_transfPfB, png_color_16p fI*trans_valuesfPfB);fP
fIfB
fB#if fI!defined(PNG_1_0_X)
fBpng_uint_16 png_get_uint_16 (png_bytep fIbuffPfB);fP
fIfB
fBpng_uint_32 png_get_uint_31 (png_bytep fIbuffPfB);fP
fIfB
fBpng_uint_32 png_get_uint_32 (png_bytep fIbuffPfB);fP
fIfB#endif
fIfB
fBpng_uint_32 png_get_unknown_chunks (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_unknown_chunkpp fIunknownsfPfB);fP
fIfB
fBpng_voidp png_get_user_chunk_ptr (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_user_height_max( png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_voidp png_get_user_transform_ptr (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_user_width_max (png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_valid (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fIflagfPfB);fP
fIfB
fBpng_int_32 png_get_x_offset_microns (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_int_32 png_get_x_offset_pixels (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_x_pixels_per_meter (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_int_32 png_get_y_offset_microns (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_int_32 png_get_y_offset_pixels (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_y_pixels_per_meter (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBpng_uint_32 png_get_compression_buffer_size (png_structp fIpng_ptrfPfB);fP
fIfB
fBint png_handle_as_unknown (png_structp fPfIpng_ptrfPfB, png_bytep fIchunk_namefPfB);fP
fIfB
fBvoid png_init_io (png_structp fPfIpng_ptrfPfB, FILE fI*fpfPfB);fP
fIfB
fBDEPRECATED: void png_info_init (png_infop fIinfo_ptrfPfB);fP
fIfB
fBDEPRECATED: void png_info_init_2 (png_infopp fPfIptr_ptrfPfB, png_size_t fIpng_info_struct_sizefPfB);fP
fIfB
fBpng_voidp png_malloc (png_structp fPfIpng_ptrfPfB, png_uint_32 fIsizefPfB);fP
fIfB
fBpng_voidp png_malloc_default(png_structp fPfIpng_ptrfPfB, png_uint_32 fIsizefPfB);fP
fIfB
fBvoidp png_memcpy (png_voidp fPfIs1fPfB, png_voidp fPfIs2fPfB, png_size_t fIsizefPfB);fP
fIfB
fBpng_voidp png_memcpy_check (png_structp fPfIpng_ptrfPfB, png_voidp fPfIs1fPfB, png_voidp fPfIs2fPfB, png_uint_32 fIsizefPfB);fP
fIfB
fBvoidp png_memset (png_voidp fPfIs1fPfB, int fPfIvaluefPfB, png_size_t fIsizefPfB);fP
fIfB
fBpng_voidp png_memset_check (png_structp fPfIpng_ptrfPfB, png_voidp fPfIs1fPfB, int fPfIvaluefPfB, png_uint_32 fIsizefPfB);fP
fIfB
fBDEPRECATED: void png_permit_empty_plte (png_structp fPfIpng_ptrfPfB, int fIempty_plte_permittedfPfB);fP
fIfB
fBvoid png_process_data (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_bytep fPfIbufferfPfB, png_size_t fIbuffer_sizefPfB);fP
fIfB
fBvoid png_progressive_combine_row (png_structp fPfIpng_ptrfPfB, png_bytep fPfIold_rowfPfB, png_bytep fInew_rowfPfB);fP
fIfB
fBvoid png_read_destroy (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_infop fIend_info_ptrfPfB);fP
fIfB
fBvoid png_read_end (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBvoid png_read_image (png_structp fPfIpng_ptrfPfB, png_bytepp fIimagefPfB);fP
fIfB
fBDEPRECATED: void png_read_init (png_structp fIpng_ptrfPfB);fP
fIfB
fBDEPRECATED: void png_read_init_2 (png_structpp fPfIptr_ptrfPfB, png_const_charp fPfIuser_png_verfPfB, png_size_t fPfIpng_struct_sizefPfB, png_size_t fIpng_info_sizefPfB);fP
fIfB
fBvoid png_read_info (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBvoid png_read_png (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fPfItransformsfPfB, png_voidp fIparamsfPfB);fP
fIfB
fBvoid png_read_row (png_structp fPfIpng_ptrfPfB, png_bytep fPfIrowfPfB, png_bytep fIdisplay_rowfPfB);fP
fIfB
fBvoid png_read_rows (png_structp fPfIpng_ptrfPfB, png_bytepp fPfIrowfPfB, png_bytepp fPfIdisplay_rowfPfB, png_uint_32 fInum_rowsfPfB);fP
fIfB
fBvoid png_read_update_info (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fB#if fI!defined(PNG_1_0_X)
fBpng_save_int_32 (png_bytep fPfIbuffPfB, png_int_32 fIifPfB);fP
fIfB
fBvoid png_save_uint_16 (png_bytep fPfIbuffPfB, unsigned int fIifPfB);fP
fIfB
fBvoid png_save_uint_32 (png_bytep fPfIbuffPfB, png_uint_32 fIifPfB);fP
fIfB
fBvoid png_set_add_alpha (png_structp fPfIpng_ptrfPfB, png_uint_32 fPfIfillerfPfB, int fIflagsfPfB);fP
fIfB#endif
fIfB
fBvoid png_set_background (png_structp fPfIpng_ptrfPfB, png_color_16p fPfIbackground_colorfPfB, int fPfIbackground_gamma_codefPfB, int fPfIneed_expandfPfB, double fIbackground_gammafPfB);fP
fIfB
fBvoid png_set_bgr (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_bKGD (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_color_16p fIbackgroundfPfB);fP
fIfB
fBvoid png_set_cHRM (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, double fPfIwhite_xfPfB, double fPfIwhite_yfPfB, double fPfIred_xfPfB, double fPfIred_yfPfB, double fPfIgreen_xfPfB, double fPfIgreen_yfPfB, double fPfIblue_xfPfB, double fIblue_yfPfB);fP
fIfB
fBvoid png_set_cHRM_fixed (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfIwhite_xfPfB, png_uint_32 fPfIwhite_yfPfB, png_uint_32 fPfIred_xfPfB, png_uint_32 fPfIred_yfPfB, png_uint_32 fPfIgreen_xfPfB, png_uint_32 fPfIgreen_yfPfB, png_uint_32 fPfIblue_xfPfB, png_uint_32 fIblue_yfPfB);fP
fIfB
fBvoid png_set_compression_level (png_structp fPfIpng_ptrfPfB, int fIlevelfPfB);fP
fIfB
fBvoid png_set_compression_mem_level (png_structp fPfIpng_ptrfPfB, int fImem_levelfPfB);fP
fIfB
fBvoid png_set_compression_method (png_structp fPfIpng_ptrfPfB, int fImethodfPfB);fP
fIfB
fBvoid png_set_compression_strategy (png_structp fPfIpng_ptrfPfB, int fIstrategyfPfB);fP
fIfB
fBvoid png_set_compression_window_bits (png_structp fPfIpng_ptrfPfB, int fIwindow_bitsfPfB);fP
fIfB
fBvoid png_set_crc_action (png_structp fPfIpng_ptrfPfB, int fPfIcrit_actionfPfB, int fIancil_actionfPfB);fP
fIfB
fBvoid png_set_dither (png_structp fPfIpng_ptrfPfB, png_colorp fPfIpalettefPfB, int fPfInum_palettefPfB, int fPfImaximum_colorsfPfB, png_uint_16p fPfIhistogramfPfB, int fIfull_ditherfPfB);fP
fIfB
fBvoid png_set_error_fn (png_structp fPfIpng_ptrfPfB, png_voidp fPfIerror_ptrfPfB, png_error_ptr fPfIerror_fnfPfB, png_error_ptr fIwarning_fnfPfB);fP
fIfB
fBvoid png_set_expand (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_expand_gray_1_2_4_to_8(png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_filler (png_structp fPfIpng_ptrfPfB, png_uint_32 fPfIfillerfPfB, int fIflagsfPfB);fP
fIfB
fBvoid png_set_filter (png_structp fPfIpng_ptrfPfB, int fPfImethodfPfB, int fIfiltersfPfB);fP
fIfB
fBvoid png_set_filter_heuristics (png_structp fPfIpng_ptrfPfB, int fPfIheuristic_methodfPfB, int fPfInum_weightsfPfB, png_doublep fPfIfilter_weightsfPfB, png_doublep fIfilter_costsfPfB);fP
fIfB
fBvoid png_set_flush (png_structp fPfIpng_ptrfPfB, int fInrowsfPfB);fP
fIfB
fBvoid png_set_gamma (png_structp fPfIpng_ptrfPfB, double fPfIscreen_gammafPfB, double fIdefault_file_gammafPfB);fP
fIfB
fBvoid png_set_gAMA (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, double fIfile_gammafPfB);fP
fIfB
fBvoid png_set_gAMA_fixed (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fIfile_gammafPfB);fP
fIfB
fBvoid png_set_gray_1_2_4_to_8(png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_gray_to_rgb (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_hIST (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_16p fIhistfPfB);fP
fIfB
fBvoid png_set_iCCP (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_charp fPfInamefPfB, int fPfIcompression_typefPfB, png_charp fPfIprofilefPfB, png_uint_32 fIproflenfPfB);fP
fIfB
fBint png_set_interlace_handling (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_invalid (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fImaskfPfB);fP
fIfB
fBvoid png_set_invert_alpha (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_invert_mono (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_IHDR (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfIwidthfPfB, png_uint_32 fPfIheightfPfB, int fPfIbit_depthfPfB, int fPfIcolor_typefPfB, int fPfIinterlace_typefPfB, int fPfIcompression_typefPfB, int fIfilter_typefPfB);fP
fIfB
fBvoid png_set_keep_unknown_chunks (png_structp fPfIpng_ptrfPfB, int fPfIkeepfPfB, png_bytep fPfIchunk_listfPfB, int fInum_chunksfPfB);fP
fIfB
fBvoid png_set_mem_fn(png_structp fPfIpng_ptrfPfB, png_voidp fPfImem_ptrfPfB, png_malloc_ptr fPfImalloc_fnfPfB, png_free_ptr fIfree_fnfPfB);fP
fIfB
fBvoid png_set_oFFs (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfIoffset_xfPfB, png_uint_32 fPfIoffset_yfPfB, int fIunit_typefPfB);fP
fIfB
fBvoid png_set_packing (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_packswap (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_palette_to_rgb(png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_pCAL (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_charp fPfIpurposefPfB, png_int_32 fPfIX0fPfB, png_int_32 fPfIX1fPfB, int fPfItypefPfB, int fPfInparamsfPfB, png_charp fPfIunitsfPfB, png_charpp fIparamsfPfB);fP
fIfB
fBvoid png_set_pHYs (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_uint_32 fPfIres_xfPfB, png_uint_32 fPfIres_yfPfB, int fIunit_typefPfB);fP
fIfB
fBvoid png_set_progressive_read_fn (png_structp fPfIpng_ptrfPfB, png_voidp fPfIprogressive_ptrfPfB, png_progressive_info_ptr fPfIinfo_fnfPfB, png_progressive_row_ptr fPfIrow_fnfPfB, png_progressive_end_ptr fIend_fnfPfB);fP
fIfB
fBvoid png_set_PLTE (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_colorp fPfIpalettefPfB, int fInum_palettefPfB);fP
fIfB
fBvoid png_set_read_fn (png_structp fPfIpng_ptrfPfB, png_voidp fPfIio_ptrfPfB, png_rw_ptr fIread_data_fnfPfB);fP
fIfB
fBvoid png_set_read_status_fn (png_structp fPfIpng_ptrfPfB, png_read_status_ptr fIread_row_fnfPfB);fP
fIfB
fBvoid png_set_read_user_transform_fn (png_structp fPfIpng_ptrfPfB, png_user_transform_ptr fIread_user_transform_fnfPfB);fP
fIfB
fBvoid png_set_rgb_to_gray (png_structp fPfIpng_ptrfPfB, int fPfIerror_actionfPfB, double fPfIredfPfB, double fIgreenfPfB);fP
fIfB
fBvoid png_set_rgb_to_gray_fixed (png_structp fPfIpng_ptrfPfB, int error_action png_fixed_point fPfIredfPfB, png_fixed_point fIgreenfPfB);fP
fIfB
fBvoid png_set_rows (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_bytepp fIrow_pointersfPfB);fP
fIfB
fBvoid png_set_sBIT (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_color_8p fIsig_bitfPfB);fP
fIfB
fBvoid png_set_sCAL (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_charp fPfIunitfPfB, double fPfIwidthfPfB, double fIheightfPfB);fP
fIfB
fBvoid png_set_shift (png_structp fPfIpng_ptrfPfB, png_color_8p fItrue_bitsfPfB);fP
fIfB
fBvoid png_set_sig_bytes (png_structp fPfIpng_ptrfPfB, int fInum_bytesfPfB);fP
fIfB
fBvoid png_set_sPLT (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_spalette_p fPfIsplt_ptrfPfB, int fInum_spalettesfPfB);fP
fIfB
fBvoid png_set_sRGB (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fIintentfPfB);fP
fIfB
fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fIintentfPfB);fP
fIfB
fBvoid png_set_strip_16 (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_strip_alpha (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_swap (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_swap_alpha (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_set_text (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_textp fPfItext_ptrfPfB, int fInum_textfPfB);fP
fIfB
fBvoid png_set_tIME (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_timep fImod_timefPfB);fP
fIfB
fBvoid png_set_tRNS (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_bytep fPfItransfPfB, int fPfInum_transfPfB, png_color_16p fItrans_valuesfPfB);fP
fIfB
fBvoid png_set_tRNS_to_alpha(png_structp fIpng_ptrfPfB);fP
fIfB
fBpng_uint_32 png_set_unknown_chunks (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, png_unknown_chunkp fPfIunknownsfPfB, int fPfInumfPfB, int fIlocationfPfB);fP
fIfB
fBvoid png_set_unknown_chunk_location(png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fPfIchunkfPfB, int fIlocationfPfB);fP
fIfB
fBvoid png_set_read_user_chunk_fn (png_structp fPfIpng_ptrfPfB, png_voidp fPfIuser_chunk_ptrfPfB, png_user_chunk_ptr fIread_user_chunk_fnfPfB);fP
fIfB
fBvoid png_set_user_limits (png_structp fPfIpng_ptrfPfB, png_uint_32 fPfIuser_width_maxfPfB, png_uint_32 fIuser_height_maxfPfB);fP
fIfB
fBvoid png_set_user_transform_info (png_structp fPfIpng_ptrfPfB, png_voidp fPfIuser_transform_ptrfPfB, int fPfIuser_transform_depthfPfB, int fIuser_transform_channelsfPfB);fP
fIfB
fBvoid png_set_write_fn (png_structp fPfIpng_ptrfPfB, png_voidp fPfIio_ptrfPfB, png_rw_ptr fPfIwrite_data_fnfPfB, png_flush_ptr fIoutput_flush_fnfPfB);fP
fIfB
fBvoid png_set_write_status_fn (png_structp fPfIpng_ptrfPfB, png_write_status_ptr fIwrite_row_fnfPfB);fP
fIfB
fBvoid png_set_write_user_transform_fn (png_structp fPfIpng_ptrfPfB, png_user_transform_ptr fIwrite_user_transform_fnfPfB);fP
fIfB
fBvoid png_set_compression_buffer_size(png_structp fPfIpng_ptrfPfB, png_uint_32 fIsizefPfB);fP
fIfB
fBint png_sig_cmp (png_bytep fPfIsigfPfB, png_size_t fPfIstartfPfB, png_size_t fInum_to_checkfPfB);fP
fIfB
fBvoid png_start_read_image (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_warning (png_structp fPfIpng_ptrfPfB, png_const_charp fImessagefPfB);fP
fIfB
fBvoid png_write_chunk (png_structp fPfIpng_ptrfPfB, png_bytep fPfIchunk_namefPfB, png_bytep fPfIdatafPfB, png_size_t fIlengthfPfB);fP
fIfB
fBvoid png_write_chunk_data (png_structp fPfIpng_ptrfPfB, png_bytep fPfIdatafPfB, png_size_t fIlengthfPfB);fP
fIfB
fBvoid png_write_chunk_end (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_write_chunk_start (png_structp fPfIpng_ptrfPfB, png_bytep fPfIchunk_namefPfB, png_uint_32 fIlengthfPfB);fP
fIfB
fBvoid png_write_destroy (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_write_end (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBvoid png_write_flush (png_structp fIpng_ptrfPfB);fP
fIfB
fBvoid png_write_image (png_structp fPfIpng_ptrfPfB, png_bytepp fIimagefPfB);fP
fIfB
fBDEPRECATED: void png_write_init (png_structp fIpng_ptrfPfB);fP
fIfB
fBDEPRECATED: void png_write_init_2 (png_structpp fPfIptr_ptrfPfB, png_const_charp fPfIuser_png_verfPfB, png_size_t fPfIpng_struct_sizefPfB, png_size_t fIpng_info_sizefPfB);fP
fIfB
fBvoid png_write_info (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBvoid png_write_info_before_PLTE (png_structp fPfIpng_ptrfPfB, png_infop fIinfo_ptrfPfB);fP
fIfB
fBvoid png_write_png (png_structp fPfIpng_ptrfPfB, png_infop fPfIinfo_ptrfPfB, int fPfItransformsfPfB, png_voidp fIparamsfPfB);fP
fIfB
fBvoid png_write_row (png_structp fPfIpng_ptrfPfB, png_bytep fIrowfPfB);fP
fIfB
fBvoid png_write_rows (png_structp fPfIpng_ptrfPfB, png_bytepp fPfIrowfPfB, png_uint_32 fInum_rowsfPfB);fP
fIfB
fBvoidpf png_zalloc (voidpf fPfIpng_ptrfPfB, uInt fPfIitemsfPfB, uInt fIsizefPfB);fP
fIfB
fBvoid png_zfree (voidpf fPfIpng_ptrfPfB, voidpf fIptrfPfB);fP
fIfB
.SH DESCRIPTION
The
.I libpng
library supports encoding, decoding, and various manipulations of
the Portable Network Graphics (PNG) format image files. It uses the
.IR zlib(3)
compression library.
Following is a copy of the libpng.txt file that accompanies libpng.
.SH LIBPNG.TXT
libpng.txt - A description on how to use and modify libpng
libpng version 1.2.34 - December 18, 2008
Updated and distributed by Glenn Randers-Pehrson
<glennrp at users.sourceforge.net>
For conditions of distribution and use, see copyright
notice in png.h.
Based on:
libpng versions 0.97, January 1998, through 1.2.34 - December 18, 2008
Updated and distributed by Glenn Randers-Pehrson
libpng 1.0 beta 6 version 0.96 May 28, 1997
Updated and distributed by Andreas Dilger
libpng 1.0 beta 2 - version 0.88 January 26, 1996
For conditions of distribution and use, see copyright
Schalnat, Group 42, Inc.
Updated/rewritten per request in the libpng FAQ
December 18, 1995 & January 20, 1996
.SH I. Introduction
This file describes how to use and modify the PNG reference library
(known as libpng) for your own use. There are five sections to this
file: introduction, structures, reading, writing, and modification and
configuration notes for various special platforms. In addition to this
file, example.c is a good starting point for using the library, as
it is heavily commented and should include everything most people
will need. We assume that libpng is already installed; see the
INSTALL file for instructions on how to install libpng.
For examples of libpng usage, see the files "example.c", "pngtest.c",
and the files in the "contrib" directory, all of which are included in the
libpng distribution.
Libpng was written as a companion to the PNG specification, as a way
of reducing the amount of time and effort it takes to support the PNG
file format in application programs.
The PNG specification (second edition), November 2003, is available as
a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
<http://www.w3.org/TR/2003/REC-PNG-20031110/
The W3C and ISO documents have identical technical content.
The PNG-1.2 specification is available at
<http://www.libpng.org/pub/png/documents/>. It is technically equivalent
to the PNG specification (second edition) but has some additional material.
The PNG-1.0 specification is available
as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
Some additional chunks are described in the special-purpose public chunks
documents at <http://www.libpng.org/pub/png/documents/>.
Other information
about PNG, and the latest version of libpng, can be found at the PNG home
page, <http://www.libpng.org/pub/png/>.
Most users will not have to modify the library significantly; advanced
users may want to modify it more. All attempts were made to make it as
complete as possible, while keeping the code easy to understand.
Currently, this library only supports C. Support for other languages
is being considered.
Libpng has been designed to handle multiple sessions at one time,
to be easily modifiable, to be portable to the vast majority of
machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
to use. The ultimate goal of libpng is to promote the acceptance of
the PNG file format in whatever way possible. While there is still
work to be done (see the TODO file), libpng should cover the
majority of the needs of its users.
Libpng uses zlib for its compression and decompression of PNG files.
Further information about zlib, and the latest version of zlib, can
be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
The zlib compression utility is a general purpose utility that is
useful for more than PNG files, and can be used without libpng.
See the documentation delivered with zlib for more details.
You can usually find the source files for the zlib utility wherever you
find the libpng source files.
Libpng is thread safe, provided the threads are using different
instances of the structures. Each thread should have its own
png_struct and png_info instances, and thus its own image.
Libpng does not protect itself against two threads using the
same instance of a structure.
.SH II. Structures
There are two main structures that are important to libpng, png_struct
and png_info. The first, png_struct, is an internal structure that
will not, for the most part, be used by a user except as the first
variable passed to every libpng function call.
The png_info structure is designed to provide information about the
PNG file. At one time, the fields of png_info were intended to be
directly accessible to the user. However, this tended to cause problems
with applications using dynamically loaded libraries, and as a result
a set of interface functions for png_info (the png_get_*() and png_set_*()
functions) was developed. The fields of png_info are still available for
older applications, but it is suggested that applications use the new
interfaces if at all possible.
Applications that do make direct access to the members of png_struct (except
for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
and applications that make direct access to the members of png_info must
be recompiled if they were compiled or loaded with libpng version 1.0.6,
in which the members were in a different order. In version 1.0.7, the
members of the png_info structure reverted to the old order, as they were
in versions 0.97c through 1.0.5. Starting with version 2.0.0, both
structures are going to be hidden, and the contents of the structures will
only be accessible through the png_get/png_set functions.
The png.h header file is an invaluable reference for programming with libpng.
And while I'm on the topic, make sure you include the libpng header file:
#include <png.h>
.SH III. Reading
We'll now walk you through the possible functions to call when reading
in a PNG file sequentially, briefly explaining the syntax and purpose
of each one. See example.c and png.h for more detail. While
progressive reading is covered in the next section, you will still
need some of the functions discussed in this section to read a PNG
file.
.SS Setup
You will want to do the I/O initialization(*) before you get into libpng,
so if it doesn't work, you don't have much to undo. Of course, you
will also want to insure that you are, in fact, dealing with a PNG
file. Libpng provides a simple check to see if a file is a PNG file.
To use it, pass in the first 1 to 8 bytes of the file to the function
png_sig_cmp(), and it will return 0 if the bytes match the corresponding
bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes
you pass in, the greater the accuracy of the prediction.
If you are intending to keep the file pointer open for use in libpng,
you must ensure you don't read more than 8 bytes from the beginning
of the file, and you also have to make a call to png_set_sig_bytes_read()
with the number of bytes you read from the beginning. Libpng will
then only check the bytes (if any) that your program didn't read.
(*): If you are not using the standard I/O functions, you will need
to replace them with custom functions. See the discussion under
Customizing libpng.
FILE *fp = fopen(file_name, "rb");
if (!fp)
{
return (ERROR);
}
fread(header, 1, number, fp);
is_png = !png_sig_cmp(header, 0, number);
if (!is_png)
{
return (NOT_PNG);
}
Next, png_struct and png_info need to be allocated and initialized. In
order to ensure that the size of these structures is correct even with a
dynamically linked libpng, there are functions to initialize and
allocate the structures. We also pass the library version, optional
pointers to error handling functions, and a pointer to a data struct for
use by the error functions, if necessary (the pointer and functions can
be NULL if the default error handlers are to be used). See the section
on Changes to Libpng below regarding the old initialization functions.
The structure allocation functions quietly return NULL if they fail to
create the structure, so your application should check for that.
png_structp png_ptr = png_create_read_struct
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn);
if (!png_ptr)
return (ERROR);
png_infop info_ptr = png_create_info_struct(png_ptr);
if (!info_ptr)
{
png_destroy_read_struct(&png_ptr,
(png_infopp)NULL, (png_infopp)NULL);
return (ERROR);
}
png_infop end_info = png_create_info_struct(png_ptr);
if (!end_info)
{
png_destroy_read_struct(&png_ptr, &info_ptr,
(png_infopp)NULL);
return (ERROR);
}
If you want to use your own memory allocation routines,
define PNG_USER_MEM_SUPPORTED and use
png_create_read_struct_2() instead of png_create_read_struct():
png_structp png_ptr = png_create_read_struct_2
(PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
user_error_fn, user_warning_fn, (png_voidp)
user_mem_ptr, user_malloc_fn, user_free_fn);
The error handling routines passed to png_create_read_struct()
and the memory alloc/free routines passed to png_create_struct_2()
are only necessary if you are not using the libpng supplied error
handling and memory alloc/free functions.
When libpng encounters an error, it expects to longjmp back
to your routine. Therefore, you will need to call setjmp and pass
your png_jmpbuf(png_ptr). If you read the file from different
routines, you will need to update the jmpbuf field every time you enter
a new routine that will call a png_*() function.
See your documentation of setjmp/longjmp for your compiler for more
information on setjmp/longjmp. See the discussion on libpng error
handling in the Customizing Libpng section below for more information
on the libpng error handling. If an error occurs, and libpng longjmp's
back to your setjmp, you will want to call png_destroy_read_struct() to
free any memory.
if (setjmp(png_jmpbuf(png_ptr)))
{
png_destroy_read_struct(&png_ptr, &info_ptr,
&end_info);
fclose(fp);
return (ERROR);
}
If you would rather avoid the complexity of setjmp/longjmp issues,
you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
errors will result in a call to PNG_ABORT() which defaults to abort().
Now you need to set up the input code. The default for libpng is to
use the C function fread(). If you use this, you will need to pass a
valid FILE * in the function png_init_io(). Be sure that the file is
opened in binary mode. If you wish to handle reading data in another
way, you need not call the png_init_io() function, but you must then
implement the libpng I/O methods discussed in the Customizing Libpng
section below.
png_init_io(png_ptr, fp);
If you had previously opened the file and read any of the signature from
the beginning in order to see if this was a PNG file, you need to let
libpng know that there are some bytes missing from the start of the file.
png_set_sig_bytes(png_ptr, number);
.SS Setting up callback code
You can set up a callback function to handle any unknown chunks in the
input stream. You must supply the function
read_chunk_callback(png_ptr ptr,
png_unknown_chunkp chunk);
{
/* The unknown chunk structure contains your
chunk data, along with similar data for any other
unknown chunks: */
png_byte name[5];
png_byte *data;
png_size_t size;
/* Note that libpng has already taken care of
the CRC handling */
/* put your code here. Search for your chunk in the
unknown chunk structure, process it, and return one
of the following: */
return (-n); /* chunk had an error */
return (0); /* did not recognize */
return (n); /* success */
}
(You can give your function another name that you like instead of
"read_chunk_callback")
To inform libpng about your function, use
png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
read_chunk_callback);
This names not only the callback function, but also a user pointer that
you can retrieve with
png_get_user_chunk_ptr(png_ptr);
If you call the png_set_read_user_chunk_fn() function, then all unknown
chunks will be saved when read, in case your callback function will need
one or more of them. This behavior can be changed with the
png_set_keep_unknown_chunks() function, described below.
At this point, you can set up a callback function that will be
called after each row has been read, which you can use to control
a progress meter or the like. It's demonstrated in pngtest.c.
You must supply a function
void read_row_callback(png_ptr ptr, png_uint_32 row,
int pass);
{
/* put your code here */
}
(You can give it another name that you like instead of "read_row_callback")
To inform libpng about your function, use
png_set_read_status_fn(png_ptr, read_row_callback);
.SS Width and height limits
The PNG specification allows the width and height of an image to be as
large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
Since very few applications really need to process such large images,
we have imposed an arbitrary 1-million limit on rows and columns.
Larger images will be rejected immediately with a png_error() call. If
you wish to override this limit, you can use
png_set_user_limits(png_ptr, width_max, height_max);
to set your own limits, or use width_max = height_max = 0x7fffffffL
to allow all valid dimensions (libpng may reject some very large images
anyway because of potential buffer overflow conditions).
You should put this statement after you create the PNG structure and
before calling png_read_info(), png_read_png(), or png_process_data().
If you need to retrieve the limits that are being applied, use
width_max = png_get_user_width_max(png_ptr);
height_max = png_get_user_height_max(png_ptr);
.SS Unknown-chunk handling
Now you get to set the way the library processes unknown chunks in the
input PNG stream. Both known and unknown chunks will be read. Normal
behavior is that known chunks will be parsed into information in
various info_ptr members while unknown chunks will be discarded. This
behavior can be wasteful if your application will never use some known
chunk types. To change this, you can call:
png_set_keep_unknown_chunks(png_ptr, keep,
chunk_list, num_chunks);
keep - 0: default unknown chunk handling
1: ignore; do not keep
2: keep only if safe-to-copy
3: keep even if unsafe-to-copy
You can use these definitions:
PNG_HANDLE_CHUNK_AS_DEFAULT 0
PNG_HANDLE_CHUNK_NEVER 1
PNG_HANDLE_CHUNK_IF_SAFE 2
PNG_HANDLE_CHUNK_ALWAYS 3
chunk_list - list of chunks affected (a byte string,
five bytes per chunk, NULL or '' if
num_chunks is 0)
num_chunks - number of chunks affected; if 0, all
unknown chunks are affected. If nonzero,
only the chunks in the list are affected
Unknown chunks declared in this way will be saved as raw data onto a
list of png_unknown_chunk structures. If a chunk that is normally
known to libpng is named in the list, it will be handled as unknown,
according to the "keep" directive. If a chunk is named in successive
instances of png_set_keep_unknown_chunks(), the final instance will
take precedence. The IHDR and IEND chunks should not be named in
chunk_list; if they are, libpng will process them normally anyway.
Here is an example of the usage of png_set_keep_unknown_chunks(),
where the private "vpAg" chunk will later be processed by a user chunk
callback function:
png_byte vpAg[5]={118, 112, 65, 103, (png_byte) ''};
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
png_byte unused_chunks[]=
{
104, 73, 83, 84, (png_byte) '', /* hIST */
105, 84, 88, 116, (png_byte) '', /* iTXt */
112, 67, 65, 76, (png_byte) '', /* pCAL */
115, 67, 65, 76, (png_byte) '', /* sCAL */
115, 80, 76, 84, (png_byte) '', /* sPLT */
116, 73, 77, 69, (png_byte) '', /* tIME */
};
#endif
...
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
/* ignore all unknown chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
/* except for vpAg: */
png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
/* also ignore unused known chunks: */
png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
(int)sizeof(unused_chunks)/5);
#endif
.SS The high-level read interface
At this point there are two ways to proceed; through the high-level
read interface, or through a sequence of low-level read operations.
You can use the high-level interface if (a) you are willing to read
the entire image into memory, and (b) the input transformations
you want to do are limited to the following set:
PNG_TRANSFORM_IDENTITY No transformation
PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
8 bits
PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
samples to bytes
PNG_TRANSFORM_PACKSWAP Change order of packed
pixels to LSB first
PNG_TRANSFORM_EXPAND Perform set_expand()
PNG_TRANSFORM_INVERT_MONO Invert monochrome images
PNG_TRANSFORM_SHIFT Normalize pixels to the
sBIT depth
PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
to BGRA
PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
to AG
PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
to transparency
PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
(This excludes setting a background color, doing gamma transformation,
dithering, and setting filler.) If this is the case, simply do this:
png_read_png(png_ptr, info_ptr, png_transforms, NULL)
where png_transforms is an integer containing the bitwise OR of
some set of transformation flags. This call is equivalent to png_read_info(),
followed the set of transformations indicated by the transform mask,
then png_read_image(), and finally png_read_end().
(The final parameter of this call is not yet used. Someday it might point
to transformation parameters required by some future input transform.)
You must use png_transforms and not call any png_set_transform() functions
when you use png_read_png().
After you have called png_read_png(), you can retrieve the image data
with
row_pointers = png_get_rows(png_ptr, info_ptr);
where row_pointers is an array of pointers to the pixel data for each row:
png_bytep row_pointers[height];
If you know your image size and pixel size ahead of time, you can allocate
row_pointers prior to calling png_read_png() with
if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
png_error (png_ptr,
"Image is too tall to process in memory");
if (width > PNG_UINT_32_MAX/pixel_size)
png_error (png_ptr,
"Image is too wide to process in memory");
row_pointers = png_malloc(png_ptr,
height*png_sizeof(png_bytep));
for (int i=0; i<height, i++)
row_pointers[i]=png_malloc(png_ptr,
width*pixel_size);
png_set_rows(png_ptr, info_ptr, &row_pointers);
Alternatively you could allocate your image in one big block and define
row_pointers[i] to point into the proper places in your block.
If you use png_set_rows(), the application is responsible for freeing
row_pointers (and row_pointers[i], if they were separately allocated).
If you don't allocate row_pointers ahead of time, png_read_png() will
do it, and it'll be free'ed when you call png_destroy_*().
.SS The low-level read interface
If you are going the low-level route, you are now ready to read all
the file information up to the actual image data. You do this with a
call to png_read_info().
png_read_info(png_ptr, info_ptr);
This will process all chunks up to but not including the image data.
.SS Querying the info structure
Functions are used to get the information from the info_ptr once it
has been read. Note that these fields may not be completely filled
in until png_read_end() has read the chunk data following the image.
png_get_IHDR(png_ptr, info_ptr, &width, &height,
&bit_depth, &color_type, &interlace_type,
&compression_type, &filter_method);
width - holds the width of the image
in pixels (up to 2^31).
height - holds the height of the image
in pixels (up to 2^31).
bit_depth - holds the bit depth of one of the
image channels. (valid values are
1, 2, 4, 8, 16 and depend also on
the color_type. See also
significant bits (sBIT) below).
color_type - describes which color/alpha channels
are present.
PNG_COLOR_TYPE_GRAY
(bit depths 1, 2, 4, 8, 16)
PNG_COLOR_TYPE_GRAY_ALPHA
(bit depths 8, 16)
PNG_COLOR_TYPE_PALETTE
(bit depths 1, 2, 4, 8)
PNG_COLOR_TYPE_RGB
(bit_depths 8, 16)
PNG_COLOR_TYPE_RGB_ALPHA
(bit_depths 8, 16)
PNG_COLOR_MASK_PALETTE
PNG_COLOR_MASK_COLOR
PNG_COLOR_MASK_ALPHA
filter_method - (must be PNG_FILTER_TYPE_BASE
for PNG 1.0, and can also be
PNG_INTRAPIXEL_DIFFERENCING if
the PNG datastream is embedded in
a MNG-1.0 datastream)
compression_type - (must be PNG_COMPRESSION_TYPE_BASE
for PNG 1.0)
interlace_type - (PNG_INTERLACE_NONE or
PNG_INTERLACE_ADAM7)
Any or all of interlace_type, compression_type, of
filter_method can be NULL if you are
not interested in their values.
channels = png_get_channels(png_ptr, info_ptr);
channels - number of channels of info for the
color type (valid values are 1 (GRAY,
PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
4 (RGB_ALPHA or RGB + filler byte))
rowbytes = png_get_rowbytes(png_ptr, info_ptr);
rowbytes - number of bytes needed to hold a row
signature = png_get_signature(png_ptr, info_ptr);
signature - holds the signature read from the
file (if any). The data is kept in
the same offset it would be if the
whole signature were read (i.e. if an
application had already read in 4
bytes of signature before starting
libpng, the remaining 4 bytes would
be in signature[4] through signature[7]
(see png_set_sig_bytes())).
width = png_get_image_width(png_ptr,
info_ptr);
height = png_get_image_height(png_ptr,
info_ptr);
bit_depth = png_get_bit_depth(png_ptr,
info_ptr);
color_type = png_get_color_type(png_ptr,
info_ptr);
filter_method = png_get_filter_type(png_ptr,
info_ptr);
compression_type = png_get_compression_type(png_ptr,
info_ptr);
interlace_type = png_get_interlace_type(png_ptr,
info_ptr);
These are also important, but their validity depends on whether the chunk
has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
data has been read, or zero if it is missing. The parameters to the
png_get_<chunk> are set directly if they are simple data types, or a pointer
into the info_ptr is returned for any complex types.
png_get_PLTE(png_ptr, info_ptr, &palette,
&num_palette);
palette - the palette for the file
(array of png_color)
num_palette - number of entries in the palette
png_get_gAMA(png_ptr, info_ptr, &gamma);
gamma - the gamma the file is written
at (PNG_INFO_gAMA)
png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
srgb_intent - the rendering intent (PNG_INFO_sRGB)
The presence of the sRGB chunk
means that the pixel data is in the
sRGB color space. This chunk also
implies specific values of gAMA and
cHRM.
png_get_iCCP(png_ptr, info_ptr, &name,
&compression_type, &profile, &proflen);
name - The profile name.
compression - The compression type; always
PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
You may give NULL to this argument to
ignore it.
profile - International Color Consortium color
profile data. May contain NULs.
proflen - length of profile data in bytes.
png_get_sBIT(png_ptr, info_ptr, &sig_bit);
sig_bit - the number of significant bits for
(PNG_INFO_sBIT) each of the gray,
red, green, and blue channels,
whichever are appropriate for the
given color type (png_color_16)
png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
&trans_values);
trans - array of transparent entries for
palette (PNG_INFO_tRNS)
trans_values - graylevel or color sample values of
the single transparent color for
non-paletted images (PNG_INFO_tRNS)
num_trans - number of transparent entries
(PNG_INFO_tRNS)
png_get_hIST(png_ptr, info_ptr, &hist);
(PNG_INFO_hIST)
hist - histogram of palette (array of
png_uint_16)
png_get_tIME(png_ptr, info_ptr, &mod_time);
mod_time - time image was last modified
(PNG_VALID_tIME)
png_get_bKGD(png_ptr, info_ptr, &background);
background - background color (PNG_VALID_bKGD)
valid 16-bit red, green and blue
values, regardless of color_type
num_comments = png_get_text(png_ptr, info_ptr,
&text_ptr, &num_text);
num_comments - number of comments
text_ptr - array of png_text holding image
comments
text_ptr[i].compression - type of compression used
on "text" PNG_TEXT_COMPRESSION_NONE
PNG_TEXT_COMPRESSION_zTXt
PNG_ITXT_COMPRESSION_NONE
PNG_ITXT_COMPRESSION_zTXt
text_ptr[i].key - keyword for comment. Must contain
1-79 characters.
text_ptr[i].text - text comments for current
keyword. Can be empty.
text_ptr[i].text_length - length of text string,
after decompression, 0 for iTXt
text_ptr[i].itxt_length - length of itxt string,
after decompression, 0 for tEXt/zTXt
text_ptr[i].lang - language of comment (empty
string for unknown).
text_ptr[i].lang_key - keyword in UTF-8
(empty string for unknown).
num_text - number of comments (same as
num_comments; you can put NULL here
to avoid the duplication)
Note while png_set_text() will accept text, language,
and translated keywords that can be NULL pointers, the
structure returned by png_get_text will always contain
regular zero-terminated C strings. They might be
empty strings but they will never be NULL pointers.
num_spalettes = png_get_sPLT(png_ptr, info_ptr,
&palette_ptr);
palette_ptr - array of palette structures holding
contents of one or more sPLT chunks
read.
num_spalettes - number of sPLT chunks read.
png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
&unit_type);
offset_x - positive offset from the left edge
of the screen
offset_y - positive offset from the top edge
of the screen
unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
&unit_type);
res_x - pixels/unit physical resolution in
x direction
res_y - pixels/unit physical resolution in
x direction
unit_type - PNG_RESOLUTION_UNKNOWN,
PNG_RESOLUTION_METER
png_get_sCAL(png_ptr, info_ptr, &unit, &width,
&height)
unit - physical scale units (an integer)
width - width of a pixel in physical scale units
height - height of a pixel in physical scale units
(width and height are doubles)
png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
&height)
unit - physical scale units (an integer)
width - width of a pixel in physical scale units
height - height of a pixel in physical scale units
(width and height are strings like "2.54")
num_unknown_chunks = png_get_unknown_chunks(png_ptr,
info_ptr, &unknowns)
unknowns - array of png_unknown_chunk
structures holding unknown chunks
unknowns[i].name - name of unknown chunk
unknowns[i].data - data of unknown chunk
unknowns[i].size - size of unknown chunk's data
unknowns[i].location - position of chunk in file
The value of "i" corresponds to the order in which the
chunks were read from the PNG file or inserted with the
png_set_unknown_chunks() function.
The data from the pHYs chunk can be retrieved in several convenient
forms:
res_x = png_get_x_pixels_per_meter(png_ptr,
info_ptr)
res_y = png_get_y_pixels_per_meter(png_ptr,
info_ptr)
res_x_and_y = png_get_pixels_per_meter(png_ptr,
info_ptr)
res_x = png_get_x_pixels_per_inch(png_ptr,
info_ptr)
res_y = png_get_y_pixels_per_inch(png_ptr,
info_ptr)
res_x_and_y = png_get_pixels_per_inch(png_ptr,
info_ptr)
aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
info_ptr)
(Each of these returns 0 [signifying "unknown"] if
the data is not present or if res_x is 0;
res_x_and_y is 0 if res_x != res_y)
The data from the oFFs chunk can be retrieved in several convenient
forms:
x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
(Each of these returns 0 [signifying "unknown" if both
x and y are 0] if the data is not present or if the
chunk is present but the unit is the pixel)
For more information, see the png_info definition in png.h and the
PNG specification for chunk contents. Be careful with trusting
rowbytes, as some of the transformations could increase the space
needed to hold a row (expand, filler, gray_to_rgb, etc.).
See png_read_update_info(), below.
A quick word about text_ptr and num_text. PNG stores comments in
keyword/text pairs, one pair per chunk, with no limit on the number
of text chunks, and a 2^31 byte limit on their size. While there are
suggested keywords, there is no requirement to restrict the use to these
strings. It is strongly suggested that keywords and text be sensible
to humans (that's the point), so don't use abbreviations. Non-printing
symbols are not allowed. See the PNG specification for more details.
There is also no requirement to have text after the keyword.
Keywords should be limited to 79 Latin-1 characters without leading or
trailing spaces, but non-consecutive spaces are allowed within the
keyword. It is possible to have the same keyword any number of times.
The text_ptr is an array of png_text structures, each holding a
pointer to a language string, a pointer to a keyword and a pointer to
a text string. The text string, language code, and translated
keyword may be empty or NULL pointers. The keyword/text
pairs are put into the array in the order that they are received.
However, some or all of the text chunks may be after the image, so, to
make sure you have read all the text chunks, don't mess with these
until after you read the stuff after the image. This will be
mentioned again below in the discussion that goes with png_read_end().
.SS Input transformations
After you've read the header information, you can set up the library
to handle any special transformations of the image data. The various
ways to transform the data will be described in the order that they
should occur. This is important, as some of these change the color
type and/or bit depth of the data, and some others only work on
certain color types and bit depths. Even though each transformation
checks to see if it has data that it can do something with, you should
make sure to only enable a transformation if it will be valid for the
data. For example, don't swap red and blue on grayscale data.
The colors used for the background and transparency values should be
supplied in the same format/depth as the current image data. They
are stored in the same format/depth as the image data in a bKGD or tRNS
chunk, so this is what libpng expects for this data. The colors are
transformed to keep in sync with the image data when an application
calls the png_read_update_info() routine (see below).
Data will be decoded into the supplied row buffers packed into bytes
unless the library has been told to transform it into another format.
For example, 4 bit/pixel paletted or grayscale data will be returned
2 pixels/byte with the leftmost pixel in the high-order bits of the
byte, unless png_set_packing() is called. 8-bit RGB data will be stored
in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
is called to insert filler bytes, either before or after each RGB triplet.
16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
byte of the color value first, unless png_set_strip_16() is called to
transform it to regular RGB RGB triplets, or png_set_filler() or
png_set_add alpha() is called to insert filler bytes, either before or
after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
be modified with
png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
The following code transforms grayscale images of less than 8 to 8 bits,
changes paletted images to RGB, and adds a full alpha channel if there is
transparency information in a tRNS chunk. This is most useful on
grayscale images with bit depths of 2 or 4 or if there is a multiple-image
viewing application that wishes to treat all images in the same way.
if (color_type == PNG_COLOR_TYPE_PALETTE)
png_set_palette_to_rgb(png_ptr);
if (color_type == PNG_COLOR_TYPE_GRAY &&
bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
if (png_get_valid(png_ptr, info_ptr,
PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
These three functions are actually aliases for png_set_expand(), added
in libpng version 1.0.4, with the function names expanded to improve code
readability. In some future version they may actually do different
things.
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
added. It expands the sample depth without changing tRNS to alpha.
At the same time, png_set_gray_1_2_4_to_8() was deprecated, and it
will be removed from a future version.
PNG can have files with 16 bits per channel. If you only can handle
8 bits per channel, this will strip the pixels down to 8 bit.
if (bit_depth == 16)
png_set_strip_16(png_ptr);
If, for some reason, you don't need the alpha channel on an image,
and you want to remove it rather than combining it with the background
(but the image author certainly had in mind that you *would* combine
it with the background, so that's what you should probably do):
if (color_type & PNG_COLOR_MASK_ALPHA)
png_set_strip_alpha(png_ptr);
In PNG files, the alpha channel in an image
is the level of opacity. If you need the alpha channel in an image to
be the level of transparency instead of opacity, you can invert the
alpha channel (or the tRNS chunk data) after it's read, so that 0 is
fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
images) is fully transparent, with
png_set_invert_alpha(png_ptr);
PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
they can, resulting in, for example, 8 pixels per byte for 1 bit
files. This code expands to 1 pixel per byte without changing the
values of the pixels:
if (bit_depth < 8)
png_set_packing(png_ptr);
PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
stored in a PNG image have been "scaled" or "shifted" up to the next
higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
8 bits/sample in the range [0, 255]). However, it is also possible to
convert the PNG pixel data back to the original bit depth of the image.
This call reduces the pixels back down to the original bit depth:
png_color_8p sig_bit;
if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
png_set_shift(png_ptr, sig_bit);
PNG files store 3-color pixels in red, green, blue order. This code
changes the storage of the pixels to blue, green, red:
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
png_set_bgr(png_ptr);
PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
into 4 or 8 bytes for windowing systems that need them in this format:
if (color_type == PNG_COLOR_TYPE_RGB)
png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
where "filler" is the 8 or 16-bit number to fill with, and the location is
either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
you want the filler before the RGB or after. This transformation
does not affect images that already have full alpha channels. To add an
opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
will generate RGBA pixels.
Note that png_set_filler() does not change the color type. If you want
to do that, you can add a true alpha channel with
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_GRAY)
png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
where "filler" contains the alpha value to assign to each pixel.
This function was added in libpng-1.2.7.
If you are reading an image with an alpha channel, and you need the
data as ARGB instead of the normal PNG format RGBA:
if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
png_set_swap_alpha(png_ptr);
For some uses, you may want a grayscale image to be represented as
RGB. This code will do that conversion:
if (color_type == PNG_COLOR_TYPE_GRAY ||
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_gray_to_rgb(png_ptr);
Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
with alpha.
if (color_type == PNG_COLOR_TYPE_RGB ||
color_type == PNG_COLOR_TYPE_RGB_ALPHA)
png_set_rgb_to_gray_fixed(png_ptr, error_action,
int red_weight, int green_weight);
error_action = 1: silently do the conversion
error_action = 2: issue a warning if the original
image has any pixel where
red != green or red != blue
error_action = 3: issue an error and abort the
conversion if the original
image has any pixel where
red != green or red != blue
red_weight: weight of red component times 100000
green_weight: weight of green component times 100000
If either weight is negative, default
weights (21268, 71514) are used.
If you have set error_action = 1 or 2, you can
later check whether the image really was gray, after processing
the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
It will return a png_byte that is zero if the image was gray or
1 if there were any non-gray pixels. bKGD and sBIT data
will be silently converted to grayscale, using the green channel
data, regardless of the error_action setting.
With red_weight+green_weight<=100000,
the normalized graylevel is computed:
int rw = red_weight * 65536;
int gw = green_weight * 65536;
int bw = 65536 - (rw + gw);
gray = (rw*red + gw*green + bw*blue)/65536;
The default values approximate those recommended in the Charles
Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
Libpng approximates this with
Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
which can be expressed with integers as
Y = (6969 * R + 23434 * G + 2365 * B)/32768
The calculation is done in a linear colorspace, if the image gamma
is known.
If you have a grayscale and you are using png_set_expand_depth(),
png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
a higher bit-depth, you must either supply the background color as a gray
value at the original file bit-depth (need_expand = 1) or else supply the
background color as an RGB triplet at the final, expanded bit depth
(need_expand = 0). Similarly, if you are reading a paletted image, you
must either supply the background color as a palette index (need_expand = 1)
or as an RGB triplet that may or may not be in the palette (need_expand = 0).
png_color_16 my_background;
png_color_16p image_background;
if (png_get_bKGD(png_ptr, info_ptr, &image_background))
png_set_background(png_ptr, image_background,
PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
else
png_set_background(png_ptr, &my_background,
PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
The png_set_background() function tells libpng to composite images
with alpha or simple transparency against the supplied background
color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
you may use this color, or supply another color more suitable for
the current display (e.g., the background color from a web page). You
need to tell libpng whether the color is in the gamma space of the
display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
know why anyone would use this, but it's here).
To properly display PNG images on any kind of system, the application needs
to know what the display gamma is. Ideally, the user will know this, and
the application will allow them to set it. One method of allowing the user
to set the display gamma separately for each system is to check for a
SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
correctly set.
Note that display_gamma is the overall gamma correction required to produce
pleasing results, which depends on the lighting conditions in the surrounding
environment. In a dim or brightly lit room, no compensation other than
the physical gamma exponent of the monitor is needed, while in a dark room
a slightly smaller exponent is better.
double gamma, screen_gamma;
if (/* We have a user-defined screen
gamma value */)
{
screen_gamma = user_defined_screen_gamma;
}
/* One way that applications can share the same
screen gamma value */
else if ((gamma_str = getenv("SCREEN_GAMMA"))
!= NULL)
{
screen_gamma = (double)atof(gamma_str);
}
/* If we don't have another value */
else
{
screen_gamma = 2.2; /* A good guess for a
PC monitor in a bright office or a dim room */
screen_gamma = 2.0; /* A good guess for a
PC monitor in a dark room */
screen_gamma = 1.7 or 1.0; /* A good
guess for Mac systems */
}
The png_set_gamma() function handles gamma transformations of the data.
Pass both the file gamma and the current screen_gamma. If the file does
not have a gamma value, you can pass one anyway if you have an idea what
it is (usually 0.45455 is a good guess for GIF images on PCs). Note
that file gammas are inverted from screen gammas. See the discussions
on gamma in the PNG specification for an excellent description of what
gamma is, and why all applications should support it. It is strongly
recommended that PNG viewers support gamma correction.
if (png_get_gAMA(png_ptr, info_ptr, &gamma))
png_set_gamma(png_ptr, screen_gamma, gamma);
else
png_set_gamma(png_ptr, screen_gamma, 0.45455);
If you need to reduce an RGB file to a paletted file, or if a paletted
file has more entries then will fit on your screen, png_set_dither()
will do that. Note that this is a simple match dither that merely
finds the closest color available. This should work fairly well with
optimized palettes, and fairly badly with linear color cubes. If you
pass a palette that is larger then maximum_colors, the file will
reduce the number of colors in the palette so it will fit into
maximum_colors. If there is a histogram, it will use it to make
more intelligent choices when reducing the palette. If there is no
histogram, it may not do as good a job.
if (color_type & PNG_COLOR_MASK_COLOR)
{
if (png_get_valid(png_ptr, info_ptr,
PNG_INFO_PLTE))
{
png_uint_16p histogram = NULL;
png_get_hIST(png_ptr, info_ptr,
&histogram);
png_set_dither(png_ptr, palette, num_palette,
max_screen_colors, histogram, 1);
}
else
{
png_color std_color_cube[MAX_SCREEN_COLORS] =
{ ... colors ... };
png_set_dither(png_ptr, std_color_cube,
MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
NULL,0);
}
}
PNG files describe monochrome as black being zero and white being one.
The following code will reverse this (make black be one and white be
zero):
if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
png_set_invert_mono(png_ptr);
This function can also be used to invert grayscale and gray-alpha images:
if (color_type == PNG_COLOR_TYPE_GRAY ||
color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
png_set_invert_mono(png_ptr);
PNG files store 16 bit pixels in network byte order (big-endian,
ie. most significant bits first). This code changes the storage to the
other way (little-endian, i.e. least significant bits first, the
way PCs store them):
if (bit_depth == 16)
png_set_swap(png_ptr);
If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
need to change the order the pixels are packed into bytes, you can use:
if (bit_depth < 8)
png_set_packswap(png_ptr);
Finally, you can write your own transformation function if none of
the existing ones meets your needs. This is done by setting a callback
with
png_set_read_user_transform_fn(png_ptr,
read_transform_fn);
You must supply the function
void read_transform_fn(png_ptr ptr, row_info_ptr
row_info, png_bytep data)
See pngtest.c for a working example. Your function will be called
after all of the other transformations have been processed.
You can also set up a pointer to a user structure for use by your
callback function, and you can inform libpng that your transform
function will change the number of channels or bit depth with the
function
png_set_user_transform_info(png_ptr, user_ptr,
user_depth, user_channels);
The user's application, not libpng, is responsible for allocating and
freeing any memory required for the user structure.
You can retrieve the pointer via the function
png_get_user_transform_ptr(). For example:
voidp read_user_transform_ptr =
png_get_user_transform_ptr(png_ptr);
The last thing to handle is interlacing; this is covered in detail below,
but you must call the function here if you want libpng to handle expansion
of the interlaced image.
number_of_passes = png_set_interlace_handling(png_ptr);
After setting the transformations, libpng can update your png_info
structure to reflect any transformations you've requested with this
call. This is most useful to update the info structure's rowbytes
field so you can use it to allocate your image memory. This function
will also update your palette with the correct screen_gamma and
background if these have been given with the calls above.
png_read_update_info(png_ptr, info_ptr);
After you call png_read_update_info(), you can allocate any
memory you need to hold the image. The row data is simply
raw byte data for all forms of images. As the actual allocation
varies among applications, no example will be given. If you
are allocating one large chunk, you will need to build an
array of pointers to each row, as it will be needed for some
of the functions below.
.SS Reading image data
After you've allocated memory, you can read the image data.
The simplest way to do this is in one function call. If you are
allocating enough memory to hold the whole image, you can just
call png_read_image() and libpng will read in all the image data
and put it in the memory area supplied. You will need to pass in
an array of pointers to each row.
This function automatically handles interlacing, so you don't need
to call png_set_interlace_handling() or call this function multiple
times, or any of that other stuff necessary with png_read_rows().
png_read_image(png_ptr, row_pointers);
where row_pointers is:
png_bytep row_pointers[height];
You can point to void or char or whatever you use for pixels.
If you don't want to read in the whole image at once, you can
use png_read_rows() instead. If there is no interlacing (check
interlace_type == PNG_INTERLACE_NONE), this is simple:
png_read_rows(png_ptr, row_pointers, NULL,
number_of_rows);
where row_pointers is the same as in the png_read_image() call.
If you are doing this just one row at a time, you can do this with
a single row_pointer instead of an array of row_pointers:
png_bytep row_pointer = row;
png_read_row(png_ptr, row_pointer, NULL);
If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
get somewhat harder. The only current (PNG Specification version 1.2)
interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
is a somewhat complicated 2D interlace scheme, known as Adam7, that
breaks down an image into seven smaller images of varying size, based
on an 8x8 grid.
libpng can fill out those images or it can give them to you "as is".
If you want them filled out, there are two ways to do that. The one