Section: C Library Functions (3)
Updated: July 18, 2013


libpng - Portable Network Graphics (PNG) Reference Library 1.6.3 


#include <png.h>

png_uint_32 png_access_version_number (void);

void png_benign_error (png_structp png_ptr, png_const_charp error);

void png_build_grayscale_palette (int bit_depth, png_colorp palette);

png_voidp png_calloc (png_structp png_ptr, png_alloc_size_t size);

void png_chunk_benign_error (png_structp png_ptr, png_const_charp error);

void png_chunk_error (png_structp png_ptr, png_const_charp error);

void png_chunk_warning (png_structp png_ptr, png_const_charp message);

void png_convert_from_struct_tm (png_timep ptime, struct tm FAR * ttime);

void png_convert_from_time_t (png_timep ptime, time_t ttime);

png_charp png_convert_to_rfc1123 (png_structp png_ptr, png_timep ptime);

png_infop png_create_info_struct (png_structp png_ptr);

png_structp png_create_read_struct (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);

png_structp png_create_read_struct_2 (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn, png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);

png_structp png_create_write_struct (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn);

png_structp png_create_write_struct_2 (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn, png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);

void png_data_freer (png_structp png_ptr, png_infop info_ptr, int freer, png_uint_32 mask));

void png_destroy_info_struct (png_structp png_ptr, png_infopp info_ptr_ptr);

void png_destroy_read_struct (png_structpp png_ptr_ptr, png_infopp info_ptr_ptr, png_infopp end_info_ptr_ptr);

void png_destroy_write_struct (png_structpp png_ptr_ptr, png_infopp info_ptr_ptr);

void png_err (png_structp png_ptr);

void png_error (png_structp png_ptr, png_const_charp error);

void png_free (png_structp png_ptr, png_voidp ptr);

void png_free_chunk_list (png_structp png_ptr);

void png_free_default (png_structp png_ptr, png_voidp ptr);

void png_free_data (png_structp png_ptr, png_infop info_ptr, int num);

png_byte png_get_bit_depth (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_bKGD (png_const_structp png_ptr, png_infop info_ptr, png_color_16p *background);

png_byte png_get_channels (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_cHRM (png_const_structp png_ptr, png_const_infop info_ptr, double *white_x, double *white_y, double *red_x, double *red_y, double *green_x, double *green_y, double *blue_x, double *blue_y);

png_uint_32 png_get_cHRM_fixed (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_32 *white_x, png_uint_32 *white_y, png_uint_32 *red_x, png_uint_32 *red_y, png_uint_32 *green_x, png_uint_32 *green_y, png_uint_32 *blue_x, png_uint_32 *blue_y);

png_uint_32 png_get_cHRM_XYZ (png_structp png_ptr, png_const_infop info_ptr, double *red_X, double *red_Y, double *red_Z, double *green_X, double *green_Y, double *green_Z, double *blue_X, double *blue_Y, double *blue_Z);

png_uint_32 png_get_cHRM_XYZ_fixed (png_structp png_ptr, png_const_infop info_ptr, png_fixed_point *int_red_X, png_fixed_point *int_red_Y, png_fixed_point *int_red_Z, png_fixed_point *int_green_X, png_fixed_point *int_green_Y, png_fixed_point *int_green_Z, png_fixed_point *int_blue_X, png_fixed_point *int_blue_Y, png_fixed_point *int_blue_Z);

png_uint_32 png_get_chunk_cache_max (png_const_structp png_ptr);

png_alloc_size_t png_get_chunk_malloc_max (png_const_structp png_ptr);

png_byte png_get_color_type (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_compression_buffer_size (png_const_structp png_ptr);

png_byte png_get_compression_type (png_const_structp png_ptr, png_const_infop info_ptr);

png_byte png_get_copyright (png_const_structp png_ptr);

png_uint_32 png_get_current_row_number (png_const_structp);

png_byte png_get_current_pass_number (png_const_structp);

png_voidp png_get_error_ptr (png_const_structp png_ptr);

png_byte png_get_filter_type (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_gAMA (png_const_structp png_ptr, png_const_infop info_ptr, double *file_gamma);

png_uint_32 png_get_gAMA_fixed (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_32 *int_file_gamma);

png_byte png_get_header_ver (png_const_structp png_ptr);

png_byte png_get_header_version (png_const_structp png_ptr);

png_uint_32 png_get_hIST (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_16p *hist);

png_uint_32 png_get_iCCP (png_const_structp png_ptr, png_const_infop info_ptr, png_charpp name, int *compression_type, png_bytepp profile, png_uint_32 *proflen);

png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop info_ptr, png_uint_32 *width, png_uint_32 *height, int *bit_depth, int *color_type, int *interlace_type, int *compression_type, int *filter_type);

png_uint_32 png_get_image_height (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_image_width (png_const_structp png_ptr, png_const_infop info_ptr);

png_int_32 png_get_int_32 (png_bytep buf);

png_byte png_get_interlace_type (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_io_chunk_type (png_const_structp png_ptr);

png_voidp png_get_io_ptr (png_structp png_ptr);

png_uint_32 png_get_io_state (png_structp png_ptr);

png_byte png_get_libpng_ver (png_const_structp png_ptr);

png_voidp png_get_mem_ptr (png_const_structp png_ptr);

png_uint_32 png_get_oFFs (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_32 *offset_x, png_uint_32 *offset_y, int *unit_type);

png_uint_32 png_get_pCAL (png_const_structp png_ptr, png_const_infop info_ptr, png_charp *purpose, png_int_32 *X0, png_int_32 *X1, int *type, int *nparams, png_charp *units, png_charpp *params);

png_uint_32 png_get_pHYs (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type);

float png_get_pixel_aspect_ratio (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_pHYs_dpi (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type);

png_fixed_point png_get_pixel_aspect_ratio_fixed (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_pixels_per_inch (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_pixels_per_meter (png_const_structp png_ptr, png_const_infop info_ptr);

png_voidp png_get_progressive_ptr (png_const_structp png_ptr);

png_uint_32 png_get_PLTE (png_const_structp png_ptr, png_const_infop info_ptr, png_colorp *palette, int *num_palette);

png_byte png_get_rgb_to_gray_status (png_const_structp png_ptr);

png_uint_32 png_get_rowbytes (png_const_structp png_ptr, png_const_infop info_ptr);

png_bytepp png_get_rows (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_sBIT (png_const_structp png_ptr, png_infop info_ptr, png_color_8p *sig_bit);

void png_get_sCAL (png_const_structp png_ptr, png_const_infop info_ptr, int* unit, double* width, double* height);

void png_get_sCAL_fixed (png_const_structp png_ptr, png_const_infop info_ptr, int* unit, png_fixed_pointp width, png_fixed_pointp height);

void png_get_sCAL_s (png_const_structp png_ptr, png_const_infop info_ptr, int* unit, png_charpp width, png_charpp height);

png_bytep png_get_signature (png_const_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_sPLT (png_const_structp png_ptr, png_const_infop info_ptr, png_spalette_p *splt_ptr);

png_uint_32 png_get_sRGB (png_const_structp png_ptr, png_const_infop info_ptr, int *file_srgb_intent);

png_uint_32 png_get_text (png_const_structp png_ptr, png_const_infop info_ptr, png_textp *text_ptr, int *num_text);

png_uint_32 png_get_tIME (png_const_structp png_ptr, png_infop info_ptr, png_timep *mod_time);

png_uint_32 png_get_tRNS (png_const_structp png_ptr, png_infop info_ptr, png_bytep *trans_alpha, int *num_trans, png_color_16p *trans_color);

/* This function is really an inline macro. */

png_uint_16 png_get_uint_16 (png_bytep buf);

png_uint_32 png_get_uint_31 (png_structp png_ptr, png_bytep buf);

/* This function is really an inline macro. */

png_uint_32 png_get_uint_32 (png_bytep buf);

png_uint_32 png_get_unknown_chunks (png_const_structp png_ptr, png_const_infop info_ptr, png_unknown_chunkpp unknowns);

png_voidp png_get_user_chunk_ptr (png_const_structp png_ptr);

png_uint_32 png_get_user_height_max (png_const_structp png_ptr);

png_voidp png_get_user_transform_ptr (png_const_structp png_ptr);

png_uint_32 png_get_user_width_max (png_const_structp png_ptr);

png_uint_32 png_get_valid (png_const_structp png_ptr, png_const_infop info_ptr, png_uint_32 flag);

float png_get_x_offset_inches (png_const_structp png_ptr, png_const_infop info_ptr);

png_fixed_point png_get_x_offset_inches_fixed (png_structp png_ptr, png_const_infop info_ptr);

png_int_32 png_get_x_offset_microns (png_const_structp png_ptr, png_const_infop info_ptr);

png_int_32 png_get_x_offset_pixels (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_x_pixels_per_inch (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_x_pixels_per_meter (png_const_structp png_ptr, png_const_infop info_ptr);

float png_get_y_offset_inches (png_const_structp png_ptr, png_const_infop info_ptr);

png_fixed_point png_get_y_offset_inches_fixed (png_structp png_ptr, png_const_infop info_ptr);

png_int_32 png_get_y_offset_microns (png_const_structp png_ptr, png_const_infop info_ptr);

png_int_32 png_get_y_offset_pixels (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_y_pixels_per_inch (png_const_structp png_ptr, png_const_infop info_ptr);

png_uint_32 png_get_y_pixels_per_meter (png_const_structp png_ptr, png_const_infop info_ptr);

int png_handle_as_unknown (png_structp png_ptr, png_bytep chunk_name);

int png_image_begin_read_from_file (png_imagep image, const char *file_name);

int png_image_begin_read_from_stdio (png_imagep image, FILE* file);

int, png_image_begin_read_from_memory (png_imagep image, png_const_voidp memory, png_size_t size);

int png_image_finish_read (png_imagep image, png_colorp background, void *buffer, png_int_32 row_stride, void *colormap);

void png_image_free (png_imagep image);

int png_image_write_to_file (png_imagep image, const char *file, int convert_to_8bit, const void *buffer, png_int_32 row_stride, void *colormap);

int png_image_write_to_stdio (png_imagep image, FILE *file, int convert_to_8_bit, const void *buffer, png_int_32 row_stride, void *colormap));

void png_info_init_3 (png_infopp info_ptr, png_size_t png_info_struct_size);

void png_init_io (png_structp png_ptr, FILE *fp);

void png_longjmp (png_structp png_ptr, int val);

png_voidp png_malloc (png_structp png_ptr, png_alloc_size_t size);

png_voidp png_malloc_default (png_structp png_ptr, png_alloc_size_t size);

png_voidp png_malloc_warn (png_structp png_ptr, png_alloc_size_t size);

png_uint_32 png_permit_mng_features (png_structp png_ptr, png_uint_32 mng_features_permitted);

void png_process_data (png_structp png_ptr, png_infop info_ptr, png_bytep buffer, png_size_t buffer_size);

png_size_t png_process_data_pause (png_structp, int save);

png_uint_32 png_process_data_skip (png_structp);

void png_progressive_combine_row (png_structp png_ptr, png_bytep old_row, png_bytep new_row);

void png_read_end (png_structp png_ptr, png_infop info_ptr);

void png_read_image (png_structp png_ptr, png_bytepp image);

void png_read_info (png_structp png_ptr, png_infop info_ptr);

void png_read_png (png_structp png_ptr, png_infop info_ptr, int transforms, png_voidp params);

void png_read_row (png_structp png_ptr, png_bytep row, png_bytep display_row);

void png_read_rows (png_structp png_ptr, png_bytepp row, png_bytepp display_row, png_uint_32 num_rows);

void png_read_update_info (png_structp png_ptr, png_infop info_ptr);

int png_reset_zstream (png_structp png_ptr);

void png_save_int_32 (png_bytep buf, png_int_32 i);

void png_save_uint_16 (png_bytep buf, unsigned int i);

void png_save_uint_32 (png_bytep buf, png_uint_32 i);

void png_set_add_alpha (png_structp png_ptr, png_uint_32 filler, int flags);

void png_set_alpha_mode (png_structp png_ptr, int mode, double output_gamma);

void png_set_alpha_mode_fixed (png_structp png_ptr, int mode, png_fixed_point output_gamma);

void png_set_background (png_structp png_ptr, png_color_16p background_color, int background_gamma_code, int need_expand, double background_gamma);

void png_set_background_fixed (png_structp png_ptr, png_color_16p background_color, int background_gamma_code, int need_expand, png_uint_32 background_gamma);

void png_set_benign_errors (png_structp png_ptr, int allowed);

void png_set_bgr (png_structp png_ptr);

void png_set_bKGD (png_structp png_ptr, png_infop info_ptr, png_color_16p background);

void png_set_check_for_invalid_index(png_structrp png_ptr, int allowed);

void png_set_cHRM (png_structp png_ptr, png_infop info_ptr, double white_x, double white_y, double red_x, double red_y, double green_x, double green_y, double blue_x, double blue_y);

void png_set_cHRM_fixed (png_structp png_ptr, png_infop info_ptr, png_uint_32 white_x, png_uint_32 white_y, png_uint_32 red_x, png_uint_32 red_y, png_uint_32 green_x, png_uint_32 green_y, png_uint_32 blue_x, png_uint_32 blue_y);

void png_set_cHRM_XYZ (png_structp png_ptr, png_infop info_ptr, double red_X, double red_Y, double red_Z, double green_X, double green_Y, double green_Z, double blue_X, double blue_Y, double blue_Z);

void png_set_cHRM_XYZ_fixed (png_structp png_ptr, png_infop info_ptr, png_fixed_point int_red_X, png_fixed_point int_red_Y, png_fixed_point int_red_Z, png_fixed_point int_green_X, png_fixed_point int_green_Y, png_fixed_point int_green_Z, png_fixed_point int_blue_X, png_fixed_point int_blue_Y, png_fixed_point int_blue_Z);

void png_set_chunk_cache_max (png_structp png_ptr, png_uint_32 user_chunk_cache_max);

void png_set_compression_level (png_structp png_ptr, int level);

void png_set_compression_mem_level (png_structp png_ptr, int mem_level);

void png_set_compression_method (png_structp png_ptr, int method);

void png_set_compression_strategy (png_structp png_ptr, int strategy);

void png_set_compression_window_bits (png_structp png_ptr, int window_bits);

void png_set_crc_action (png_structp png_ptr, int crit_action, int ancil_action);

void png_set_error_fn (png_structp png_ptr, png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warning_fn);

void png_set_expand (png_structp png_ptr);

void png_set_expand_16 (png_structp png_ptr);

void png_set_expand_gray_1_2_4_to_8 (png_structp png_ptr);

void png_set_filler (png_structp png_ptr, png_uint_32 filler, int flags);

void png_set_filter (png_structp png_ptr, int method, int filters);

void png_set_filter_heuristics (png_structp png_ptr, int heuristic_method, int num_weights, png_doublep filter_weights, png_doublep filter_costs);

void png_set_filter_heuristics_fixed (png_structp png_ptr, int heuristic_method, int num_weights, png_fixed_point_p filter_weights, png_fixed_point_p filter_costs);

void png_set_flush (png_structp png_ptr, int nrows);

void png_set_gamma (png_structp png_ptr, double screen_gamma, double default_file_gamma);

void png_set_gamma_fixed (png_structp png_ptr, png_uint_32 screen_gamma, png_uint_32 default_file_gamma);

void png_set_gAMA (png_structp png_ptr, png_infop info_ptr, double file_gamma);

void png_set_gAMA_fixed (png_structp png_ptr, png_infop info_ptr, png_uint_32 file_gamma);

void png_set_gray_1_2_4_to_8 (png_structp png_ptr);

void png_set_gray_to_rgb (png_structp png_ptr);

void png_set_hIST (png_structp png_ptr, png_infop info_ptr, png_uint_16p hist);

void png_set_iCCP (png_structp png_ptr, png_infop info_ptr, png_const_charp name, int compression_type, png_const_bytep profile, png_uint_32 proflen);

int png_set_interlace_handling (png_structp png_ptr);

void png_set_invalid (png_structp png_ptr, png_infop info_ptr, int mask);

void png_set_invert_alpha (png_structp png_ptr);

void png_set_invert_mono (png_structp png_ptr);

void png_set_IHDR (png_structp png_ptr, png_infop info_ptr, png_uint_32 width, png_uint_32 height, int bit_depth, int color_type, int interlace_type, int compression_type, int filter_type);

void png_set_keep_unknown_chunks (png_structp png_ptr, int keep, png_bytep chunk_list, int num_chunks);

jmp_buf* png_set_longjmp_fn (png_structp png_ptr, png_longjmp_ptr longjmp_fn, size_t jmp_buf_size);

void png_set_chunk_malloc_max (png_structp png_ptr, png_alloc_size_t user_chunk_cache_max);

void png_set_compression_buffer_size (png_structp png_ptr, png_uint_32 size);

void png_set_mem_fn (png_structp png_ptr, png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn);

void png_set_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32 offset_x, png_uint_32 offset_y, int unit_type);

void png_set_packing (png_structp png_ptr);

void png_set_packswap (png_structp png_ptr);

void png_set_palette_to_rgb (png_structp png_ptr);

void png_set_pCAL (png_structp png_ptr, png_infop info_ptr, png_charp purpose, png_int_32 X0, png_int_32 X1, int type, int nparams, png_charp units, png_charpp params);

void png_set_pHYs (png_structp png_ptr, png_infop info_ptr, png_uint_32 res_x, png_uint_32 res_y, int unit_type);

void png_set_progressive_read_fn (png_structp png_ptr, png_voidp progressive_ptr, png_progressive_info_ptr info_fn, png_progressive_row_ptr row_fn, png_progressive_end_ptr end_fn);

void png_set_PLTE (png_structp png_ptr, png_infop info_ptr, png_colorp palette, int num_palette);

void png_set_quantize (png_structp png_ptr, png_colorp palette, int num_palette, int maximum_colors, png_uint_16p histogram, int full_quantize);

void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr read_data_fn);

void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr read_row_fn);

void png_set_read_user_chunk_fn (png_structp png_ptr, png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn);

void png_set_read_user_transform_fn (png_structp png_ptr, png_user_transform_ptr read_user_transform_fn);

void png_set_rgb_to_gray (png_structp png_ptr, int error_action, double red, double green);

void png_set_rgb_to_gray_fixed (png_structp png_ptr, int error_action png_uint_32 red, png_uint_32 green);

void png_set_rows (png_structp png_ptr, png_infop info_ptr, png_bytepp row_pointers);

void png_set_sBIT (png_structp png_ptr, png_infop info_ptr, png_color_8p sig_bit);

void png_set_sCAL (png_structp png_ptr, png_infop info_ptr, int unit, double width, double height);

void png_set_sCAL_fixed (png_structp png_ptr, png_infop info_ptr, int unit, png_fixed_point width, png_fixed_point height);

void png_set_sCAL_s (png_structp png_ptr, png_infop info_ptr, int unit, png_charp width, png_charp height);

void png_set_scale_16 (png_structp png_ptr);

void png_set_shift (png_structp png_ptr, png_color_8p true_bits);

void png_set_sig_bytes (png_structp png_ptr, int num_bytes);

void png_set_sPLT (png_structp png_ptr, png_infop info_ptr, png_spalette_p splt_ptr, int num_spalettes);

void png_set_sRGB (png_structp png_ptr, png_infop info_ptr, int srgb_intent);

void png_set_sRGB_gAMA_and_cHRM (png_structp png_ptr, png_infop info_ptr, int srgb_intent);

void png_set_strip_16 (png_structp png_ptr);

void png_set_strip_alpha (png_structp png_ptr);

void png_set_strip_error_numbers (png_structp png_ptr, png_uint_32 strip_mode);

void png_set_swap (png_structp png_ptr);

void png_set_swap_alpha (png_structp png_ptr);

void png_set_text (png_structp png_ptr, png_infop info_ptr, png_textp text_ptr, int num_text);

void png_set_text_compression_level (png_structp png_ptr, int level);

void png_set_text_compression_mem_level (png_structp png_ptr, int mem_level);

void png_set_text_compression_strategy (png_structp png_ptr, int strategy);

void png_set_text_compression_window_bits (png_structp png_ptr, int window_bits);

void png_set_text_compression_method, (png_structp png_ptr, int method));

void png_set_tIME (png_structp png_ptr, png_infop info_ptr, png_timep mod_time);

void png_set_tRNS (png_structp png_ptr, png_infop info_ptr, png_bytep trans_alpha, int num_trans, png_color_16p trans_color);

void png_set_tRNS_to_alpha (png_structp png_ptr);

png_uint_32 png_set_unknown_chunks (png_structp png_ptr, png_infop info_ptr, png_unknown_chunkp unknowns, int num, int location);

void png_set_unknown_chunk_location (png_structp png_ptr, png_infop info_ptr, int chunk, int location);

void png_set_user_limits (png_structp png_ptr, png_uint_32 user_width_max, png_uint_32 user_height_max);

void png_set_user_transform_info (png_structp png_ptr, png_voidp user_transform_ptr, int user_transform_depth, int user_transform_channels);

void png_set_write_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn);

void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr write_row_fn);

void png_set_write_user_transform_fn (png_structp png_ptr, png_user_transform_ptr write_user_transform_fn);

int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t num_to_check);

void png_start_read_image (png_structp png_ptr);

void png_warning (png_structp png_ptr, png_const_charp message);

void png_write_chunk (png_structp png_ptr, png_bytep chunk_name, png_bytep data, png_size_t length);

void png_write_chunk_data (png_structp png_ptr, png_bytep data, png_size_t length);

void png_write_chunk_end (png_structp png_ptr);

void png_write_chunk_start (png_structp png_ptr, png_bytep chunk_name, png_uint_32 length);

void png_write_end (png_structp png_ptr, png_infop info_ptr);

void png_write_flush (png_structp png_ptr);

void png_write_image (png_structp png_ptr, png_bytepp image);

void png_write_info (png_structp png_ptr, png_infop info_ptr);

void png_write_info_before_PLTE (png_structp png_ptr, png_infop info_ptr);

void png_write_png (png_structp png_ptr, png_infop info_ptr, int transforms, png_voidp params);

void png_write_row (png_structp png_ptr, png_bytep row);

void png_write_rows (png_structp png_ptr, png_bytepp row, png_uint_32 num_rows);

void png_write_sig (png_structp png_ptr);



Thelibpnglibrary supports encoding, decoding, and various manipulations ofthe Portable Network Graphics (PNG) format image files. It uses thezlib(3)compression library.Following is a copy of the libpng-manual.txt file that accompanies libpng. 


libpng-manual.txt - A description on how to use and modify libpng

 libpng version 1.6.3 - July 18, 2013
 Updated and distributed by Glenn Randers-Pehrson
 <glennrp at>
 Copyright (c) 1998-2013 Glenn Randers-Pehrson

 This document is released under the libpng license.
 For conditions of distribution and use, see the disclaimer
 and license in png.h

 Based on:

 libpng versions 0.97, January 1998, through 1.6.3 - July 18, 2013
 Updated and distributed by Glenn Randers-Pehrson
 Copyright (c) 1998-2013 Glenn Randers-Pehrson

 libpng 1.0 beta 6  version 0.96 May 28, 1997
 Updated and distributed by Andreas Dilger
 Copyright (c) 1996, 1997 Andreas Dilger

 libpng 1.0 beta 2 - version 0.88  January 26, 1996
 For conditions of distribution and use, see copyright
 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
 Schalnat, Group 42, Inc.

 Updated/rewritten per request in the libpng FAQ
 Copyright (c) 1995, 1996 Frank J. T. Wojcik
 December 18, 1995 & January 20, 1996


    I. Introduction
   II. Structures
  III. Reading
   IV. Writing
    V. Simplified API
   VI. Modifying/Customizing libpng
  VII. MNG support
 VIII. Changes to Libpng from version 0.88
   IX. Changes to Libpng from version 1.0.x to 1.2.x
    X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
   XI. Changes to Libpng from version 1.4.x to 1.5.x
  XII. Changes to Libpng from version 1.5.x to 1.6.x
 XIII. Detecting libpng
  XIV. Source code repository
   XV. Coding style
  XVI. Y2K Compliance in libpng


I. Introduction

This file describes how to use and modify the PNG reference library(known as libpng) for your own use. In addition to thisfile, example.c is a good starting point for using the library, asit is heavily commented and should include everything most peoplewill need. We assume that libpng is already installed; see theINSTALL 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 inthe libpng distribution.

Libpng was written as a companion to the PNG specification, as a wayof reducing the amount of time and effort it takes to support the PNGfile format in application programs.

The PNG specification (second edition), November 2003, is available asa W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at< W3C and ISO documents have identical technical content.

The PNG-1.2 specification is available at<>. It is technically equivalentto the PNG specification (second edition) but has some additional material.

The PNG-1.0 specification is availableas RFC 2083 <> and as aW3C Recommendation <>.

Some additional chunks are described in the special-purpose public chunksdocuments at <>.

Other informationabout PNG, and the latest version of libpng, can be found at the PNG homepage, <>.

Most users will not have to modify the library significantly; advancedusers may want to modify it more. All attempts were made to make it ascomplete as possible, while keeping the code easy to understand.Currently, this library only supports C. Support for other languagesis being considered.

Libpng has been designed to handle multiple sessions at one time,to be easily modifiable, to be portable to the vast majority ofmachines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easyto use. The ultimate goal of libpng is to promote the acceptance ofthe PNG file format in whatever way possible. While there is stillwork to be done (see the TODO file), libpng should cover themajority 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, canbe found at the zlib home page, <>.The zlib compression utility is a general purpose utility that isuseful 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 youfind the libpng source files.

Libpng is thread safe, provided the threads are using differentinstances of the structures. Each thread should have its ownpng_struct and png_info instances, and thus its own image.Libpng does not protect itself against two threads using thesame instance of a structure.


II. Structures

There are two main structures that are important to libpng, png_structand png_info. Both are internal structures that are no longer exposedin the libpng interface (as of libpng 1.5.0).

The png_info structure is designed to provide information about thePNG file. At one time, the fields of png_info were intended to bedirectly accessible to the user. However, this tended to cause problemswith applications using dynamically loaded libraries, and as a resulta set of interface functions for png_info (the png_get_*() and png_set_*()functions) was developed, and direct access to the png_info fields wasdeprecated..

The png_struct structure is the object used by the library to decode asingle image. As of 1.5.0 this structure is also not exposed.

Almost all libpng APIs require a pointer to a png_struct as the first argument.Many (in particular the png_set and png_get APIs) also require a pointerto png_info as the second argument. Some application visible macrosdefined in png.h designed for basic data access (reading and writingintegers in the PNG format) don't take a png_info pointer, but it's almostalways safe to assume that a (png_struct*) has to be passed to call an APIfunction.

You can have more than one png_info structure associated with an image,as illustrated in pngtest.c, one for information valid prior to theIDAT chunks and another (called "end_info" below) for things after them.

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>

and also (as of libpng-1.5.0) the zlib header file, if you need it:

#include <zlib.h>



The png.h header file defines a number of integral types used by theAPIs. Most of these are fairly obvious; for example types correspondingto integers of particular sizes and types for passing color values.

One exception is how non-integral numbers are handled. For applicationconvenience most APIs that take such numbers have C (double) arguments;however, internally PNG, and libpng, use 32 bit signed integers and encodethe value by multiplying by 100,000. As of libpng 1.5.0 a conveniencemacro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)which is simply (png_int_32).

All APIs that take (double) arguments also have a matching API thattakes the corresponding fixed point integer arguments. The fixed pointAPI has the same name as the floating point one with "_fixed" appended.The actual range of values permitted in the APIs is frequently less thanthe full range of (png_fixed_point) (-21474 to +21474). When APIs requirea non-negative argument the type is recorded as png_uint_32 above. Consultthe header file and the text below for more information.

Special care must be take with sCAL chunk handling because the chunk itselfuses non-integral values encoded as strings containing decimal floating pointnumbers. See the comments in the header file.



The main header file function declarations are frequently protected by Cpreprocessing directives of the form:

    #ifdef PNG_feature_SUPPORTED
    #ifdef PNG_feature_SUPPORTED

The library can be built without support for these APIs, although astandard build will have all implemented APIs. Application programsshould check the feature macros before using an API for maximumportability. From libpng 1.5.0 the feature macros set during the buildof libpng are recorded in the header file "pnglibconf.h" and this fileis always included by png.h.

If you don't need to change the library configuration from the default, skip tothe next section ("Reading").

Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) allof the build project files in the 'projects' directory simply copyscripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these buildsystems do not permit easy auto-configuration of the library - they onlysupport the default configuration.

The easiest way to make minor changes to the libpng configuration whenauto-configuration is supported is to add definitions to the command lineusing (typically) CPPFLAGS. For example:


will change the internal libpng math implementation for gamma correction andother arithmetic calculations to fixed point, avoiding the need for fastfloating point support. The result can be seen in the generated pnglibconf.h -make sure it contains the changed feature macro setting.

If you need to make more extensive configuration changes - more than one or twofeature macro settings - you can either add -DPNG_USER_CONFIG to the buildcommand line and put a list of feature macro settings in pngusr.h or you can setDFA_XTRA (a makefile variable) to a file containing the same information in theform of 'option' settings.

A. Changing pnglibconf.h

A variety of methods exist to build libpng. Not all of these supportreconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either berebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.

Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt topnglibconf.h and changing the lines defining the supported features, payingvery close attention to the 'option' information in scripts/pnglibconf.dfathat describes those features and their requirements. This is easy to getwrong.

B. Configuration using DFA_XTRA

Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a latervariant such as 'nawk' or 'gawk', is available. The configure build willautomatically find an appropriate awk and build pnglibconf.h.The scripts/pnglibconf.mak file contains a set of make rules for doing thesame thing if configure is not used, and many of the makefiles in the scriptsdirectory use this approach.

When rebuilding simply write a new file containing changed options and setDFA_XTRA to the name of this file. This causes the build to append the new fileto the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain linesof the following forms:

everything = off

This turns all optional features off. Include it at the start of pngusr.dfa tomake it easier to build a minimal configuration. You will need to turn at leastsome features on afterward to enable either reading or writing code, or both.

option feature onoption feature off

Enable or disable a single feature. This will automatically enable otherfeatures required by a feature that is turned on or disable other features thatrequire a feature which is turned off. Conflicting settings will cause an errormessage to be emitted by awk.

setting feature default value

Changes the default value of setting 'feature' to 'value'. There are a smallnumber of settings listed at the top of pnglibconf.h, they are documented in thesource code. Most of these values have performance implications for the librarybut most of them have no visible effect on the API. Some can also be overriddenfrom the API.

This method of building a customized pnglibconf.h is illustrated incontrib/pngminim/*. See the "$(PNGCONF):" target in the makefile andpngusr.dfa in these directories.

C. Configuration using PNG_USR_CONFIG

If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the filepngusr.h will automatically be included before the options inscripts/pnglibconf.dfa are processed. Your pngusr.h file should contain onlymacro definitions turning features on or off or setting settings.

Apart from the global setting "everything = off" all the options listed abovecan be set using macros in pngusr.h:

#define PNG_feature_SUPPORTED

is equivalent to:

option feature on

#define PNG_NO_feature

is equivalent to:

option feature off

#define PNG_feature value

is equivalent to:

setting feature default value

Notice that in both cases, pngusr.dfa and pngusr.h, the contents of thepngusr file you supply override the contents of scripts/pnglibconf.dfa

If confusing or incomprehensible behavior results it is possible toexamine the intermediate file pnglibconf.dfn to find the full set ofdependency information for each setting and option. Simply locate thefeature in the file and read the C comments that precede it.

This method is also illustrated in the contrib/pngminim/* makefiles andpngusr.h.


III. Reading

We'll now walk you through the possible functions to call when readingin a PNG file sequentially, briefly explaining the syntax and purposeof each one. See example.c and png.h for more detail. Whileprogressive reading is covered in the next section, you will stillneed some of the functions discussed in this section to read a PNGfile.



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, youwill also want to insure that you are, in fact, dealing with a PNGfile. 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 functionpng_sig_cmp(), and it will return 0 (false) if the bytes match thecorresponding bytes of the PNG signature, or nonzero (true) otherwise.Of course, the more bytes you pass in, the greater the accuracy of theprediction.

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 beginningof 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 willthen only check the bytes (if any) that your program didn't read.

(*): If you are not using the standard I/O functions, you will needto replace them with custom functions. See the discussion underCustomizing 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. Inorder to ensure that the size of these structures is correct even with adynamically linked libpng, there are functions to initialize andallocate the structures. We also pass the library version, optionalpointers to error handling functions, and a pointer to a data struct foruse by the error functions, if necessary (the pointer and functions canbe NULL if the default error handlers are to be used). See the sectionon Changes to Libpng below regarding the old initialization functions.The structure allocation functions quietly return NULL if they fail tocreate 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_infopp)NULL, (png_infopp)NULL);
       return (ERROR);

If you want to use your own memory allocation routines,use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and usepng_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 errorhandling and memory alloc/free functions.

When libpng encounters an error, it expects to longjmp backto your routine. Therefore, you will need to call setjmp and passyour png_jmpbuf(png_ptr). If you read the file from differentroutines, you will need to update the longjmp buffer every time you entera new routine that will call a png_*() function.

See your documentation of setjmp/longjmp for your compiler for moreinformation on setjmp/longjmp. See the discussion on libpng errorhandling in the Customizing Libpng section below for more informationon the libpng error handling. If an error occurs, and libpng longjmp'sback to your setjmp, you will want to call png_destroy_read_struct() tofree any memory.

    if (setjmp(png_jmpbuf(png_ptr)))
       png_destroy_read_struct(&png_ptr, &info_ptr,
       return (ERROR);

Pass (png_infopp)NULL instead of &end_info if you didn't createan end_info structure.

If you would rather avoid the complexity of setjmp/longjmp issues,you can compile libpng with PNG_NO_SETJMP, in which caseerrors will result in a call to PNG_ABORT() which defaults to abort().

You can #define PNG_ABORT() to a function that does somethingmore useful than abort(), as long as your function does notreturn.

Now you need to set up the input code. The default for libpng is touse the C function fread(). If you use this, you will need to pass avalid FILE * in the function png_init_io(). Be sure that the file isopened in binary mode. If you wish to handle reading data in anotherway, you need not call the png_init_io() function, but you must thenimplement the libpng I/O methods discussed in the Customizing Libpngsection below.

    png_init_io(png_ptr, fp);

If you had previously opened the file and read any of the signature fromthe beginning in order to see if this was a PNG file, you need to letlibpng know that there are some bytes missing from the start of the file.

    png_set_sig_bytes(png_ptr, number);

You can change the zlib compression buffer size to be used whilereading compressed data with

    png_set_compression_buffer_size(png_ptr, buffer_size);

where the default size is 8192 bytes. Note that the buffer sizeis changed immediately and the buffer is reallocated immediately,instead of setting a flag to be acted upon later.

If you want CRC errors to be handled in a different manner thanthe default, use

    png_set_crc_action(png_ptr, crit_action, ancil_action);

The values for png_set_crc_action() say how libpng is to handle CRC errors inancillary and critical chunks, and whether to use the data containedtherein. Note that it is impossible to "discard" data in a criticalchunk.

Choices for (int) crit_action are
   PNG_CRC_DEFAULT      0  error/quit
   PNG_CRC_ERROR_QUIT   1  error/quit
   PNG_CRC_WARN_USE     3  warn/use data
   PNG_CRC_QUIET_USE    4  quiet/use data
   PNG_CRC_NO_CHANGE    5  use the current value

Choices for (int) ancil_action are
   PNG_CRC_DEFAULT      0  error/quit
   PNG_CRC_ERROR_QUIT   1  error/quit
   PNG_CRC_WARN_DISCARD 2  warn/discard data
   PNG_CRC_WARN_USE     3  warn/use data
   PNG_CRC_QUIET_USE    4  quiet/use data
   PNG_CRC_NO_CHANGE    5  use the current value


Setting up callback code

You can set up a callback function to handle any unknown chunks in theinput stream. You must supply the function

    read_chunk_callback(png_structp png_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,

This names not only the callback function, but also a user pointer thatyou can retrieve with


If you call the png_set_read_user_chunk_fn() function, then all unknownchunks which the callback does not handle will be saved when read. You cancause them to be discarded by returning '1' ("handled") instead of '0'. Thisbehavior will change in libpng 1.7 and the default handling set by thepng_set_keep_unknown_chunks() function, described below, will be used when thecallback returns 0. If you want the existing behavior you should set the globaldefault to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all currentversions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep thedefault, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.

At this point, you can set up a callback function that will becalled after each row has been read, which you can use to controla progress meter or the like. It's demonstrated in pngtest.c.You must supply a function

    void read_row_callback(png_structp png_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);

When this function is called the row has already been completely processed andthe 'row' and 'pass' refer to the next row to be handled. For thenon-interlaced case the row that was just handled is simply one less than thepassed in row number, and pass will always be 0. For the interlaced case thesame applies unless the row value is 0, in which case the row just handled wasthe last one from one of the preceding passes. Because interlacing may skip apass you cannot be sure that the preceding pass is just 'pass-1', if you reallyneed to know what the last pass is record (row,pass) from the callback and usethe last recorded value each time.

As with the user transform you can find the output row using thePNG_ROW_FROM_PASS_ROW macro.


Unknown-chunk handling

Now you get to set the way the library processes unknown chunks in theinput PNG stream. Both known and unknown chunks will be read. Normalbehavior is that known chunks will be parsed into information invarious info_ptr members while unknown chunks will be discarded. Thisbehavior can be wasteful if your application will never use some knownchunk 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