SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Trustix libpng12-1.2.5-7tr.i586.rpm

LIBPNG

Section: C Library Functions (3)
Updated: October 3, 2002
Index 

NAME

libpng - Portable Network Graphics (PNG) Reference Library 1.2.5 

SYNOPSIS

#include <png.h>

png_uint_32 png_access_version_number (void);

int png_check_sig (png_bytep sig, int num);

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);

int png_debug(int level, png_const_charp message);

int png_debug1(int level, png_const_charp message, p1);

int png_debug2(int level, png_const_charp message, p1, p2);

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_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_uint_32 png_get_asm_flags (png_structp png_ptr);

png_byte png_get_bit_depth (png_structp png_ptr, png_infop info_ptr);

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

png_byte png_get_channels (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_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);

png_uint_32 png_get_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);

png_byte png_get_color_type (png_structp png_ptr, png_infop info_ptr);

png_byte png_get_compression_type (png_structp png_ptr, png_infop info_ptr);

png_byte png_get_copyright (png_structp png_ptr);

png_voidp png_get_error_ptr (png_structp png_ptr);

png_byte png_get_filter_type (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop info_ptr, double *file_gamma);

png_uint_32 png_get_gAMA_fixed (png_structp png_ptr, png_infop info_ptr, png_uint_32 *int_file_gamma);

png_byte png_get_header_ver (png_structp png_ptr);

png_byte png_get_header_version (png_structp png_ptr);

png_uint_32 png_get_hIST (png_structp png_ptr, png_infop info_ptr, png_uint_16p *hist);

png_uint_32 png_get_iCCP (png_structp png_ptr, png_infop info_ptr, png_charpp name, int *compression_type, png_charpp 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_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_image_width (png_structp png_ptr, png_infop info_ptr);

png_byte png_get_interlace_type (png_structp png_ptr, png_infop info_ptr);

png_voidp png_get_io_ptr (png_structp png_ptr);

png_byte png_get_libpng_ver (png_structp png_ptr);

png_voidp png_get_mem_ptr(png_structp png_ptr);

png_byte png_get_mmx_bitdepth_threshold (png_structp png_ptr);

png_uint_32 png_get_mmx_flagmask (int flag_select, int *compilerID);

png_uint_32 png_get_mmx_rowbytes_threshold (png_structp png_ptr);

png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32 *offset_x, png_uint_32 *offset_y, int *unit_type);

png_uint_32 png_get_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);

png_uint_32 png_get_pHYs (png_structp png_ptr, png_infop info_ptr, png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type);

float png_get_pixel_aspect_ratio (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_pixels_per_meter (png_structp png_ptr, png_infop info_ptr);

png_voidp png_get_progressive_ptr (png_structp png_ptr);

png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop info_ptr, png_colorp *palette, int *num_palette);

png_byte png_get_rgb_to_gray_status (png_structp png_ptr)

png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop info_ptr);

png_bytepp png_get_rows (png_structp png_ptr, png_infop info_ptr);

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

png_bytep png_get_signature (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_sPLT (png_structp png_ptr, png_infop info_ptr, png_spalette_p *splt_ptr);

png_uint_32 png_get_sRGB (png_structp png_ptr, png_infop info_ptr, int *intent);

png_uint_32 png_get_text (png_structp png_ptr, png_infop info_ptr, png_textp *text_ptr, int *num_text);

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

png_uint_32 png_get_tRNS (png_structp png_ptr, png_infop info_ptr, png_bytep *trans, int *num_trans, png_color_16p *trans_values);

png_uint_32 png_get_unknown_chunks (png_structp png_ptr, png_infop info_ptr, png_unknown_chunkpp unknowns);

png_voidp png_get_user_chunk_ptr (png_structp png_ptr);

png_voidp png_get_user_transform_ptr (png_structp png_ptr);

png_uint_32 png_get_valid (png_structp png_ptr, png_infop info_ptr, png_uint_32 flag);

png_int_32 png_get_x_offset_microns (png_structp png_ptr, png_infop info_ptr);

png_int_32 png_get_x_offset_pixels (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_x_pixels_per_meter (png_structp png_ptr, png_infop info_ptr);

png_int_32 png_get_y_offset_microns (png_structp png_ptr, png_infop info_ptr);

png_int_32 png_get_y_offset_pixels (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_y_pixels_per_meter (png_structp png_ptr, png_infop info_ptr);

png_uint_32 png_get_compression_buffer_size (png_structp png_ptr);

int png_handle_as_unknown (png_structp png_ptr, png_bytep chunk_name);

void png_init_io (png_structp png_ptr, FILE *fp);

DEPRECATED: void png_info_init (png_infop info_ptr);

DEPRECATED: void png_info_init_2 (png_infopp ptr_ptr, png_size_t png_info_struct_size);

png_voidp png_malloc (png_structp png_ptr, png_uint_32 size);

png_voidp png_malloc_default(png_structp png_ptr, png_uint_32 size);

png_voidp png_malloc_warn (png_structp png_ptr, png_uint_32 size);

voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size);

png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1, png_voidp s2, png_uint_32 size);

voidp png_memset (png_voidp s1, int value, png_size_t size);

png_voidp png_memset_check (png_structp png_ptr, png_voidp s1, int value, png_uint_32 size);

int png_mmx_support (void);

DEPRECATED: void png_permit_empty_plte (png_structp png_ptr, int empty_plte_permitted);

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

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

void png_read_destroy (png_structp png_ptr, png_infop info_ptr, png_infop end_info_ptr);

void png_read_end (png_structp png_ptr, png_infop info_ptr);

void png_read_image (png_structp png_ptr, png_bytepp image);

DEPRECATED: void png_read_init (png_structp png_ptr);

DEPRECATED: void png_read_init_2 (png_structpp ptr_ptr, png_const_charp user_png_ver, png_size_t png_struct_size, png_size_t png_info_size);

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);

png_set_asm_flags (png_structp png_ptr, png_uint_32 asm_flags);

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_bgr (png_structp png_ptr);

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

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_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_dither (png_structp png_ptr, png_colorp palette, int num_palette, int maximum_colors, png_uint_16p histogram, int full_dither);

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_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_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_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_charp name, int compression_type, png_charp 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);

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

png_set_mmx_thresholds (png_structp png_ptr, png_byte mmx_bitdepth_threshold, png_uint_32 mmx_rowbytes_threshold);

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_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_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_fixed_point red, png_fixed_point 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, png_charp unit, double width, double height);

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 intent);

void png_set_sRGB_gAMA_and_cHRM (png_structp png_ptr, png_infop info_ptr, int 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_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, int num_trans, png_color_16p trans_values);

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_read_user_chunk_fn (png_structp png_ptr, png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn);

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);

void png_set_compression_buffer_size(png_structp png_ptr, png_uint_32 size);

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_destroy (png_structp png_ptr);

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);

DEPRECATED: void png_write_init (png_structp png_ptr);

DEPRECATED: void png_write_init_2 (png_structpp ptr_ptr, png_const_charp user_png_ver, png_size_t png_struct_size, png_size_t png_info_size);

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);

 

DESCRIPTION

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.txt file that accompanies libpng. 

LIBPNG.TXT

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


 libpng version 1.2.5 - October 3, 2002
 Updated and distributed by Glenn Randers-Pehrson
 <randegAATTalum.rpi.edu>
 Copyright (c) 1998-2002 Glenn Randers-Pehrson
 For conditions of distribution and use, see copyright
 notice in png.h.


 based on:


 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

This file describes how to use and modify the PNG reference library(known as libpng) for your own use. There are five sections to thisfile: introduction, structures, reading, writing, and modification andconfiguration notes for various special platforms. 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.

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-1.2 specification is available at <http://www.libpng.org/pub/png>and at <ftp://ftp.uu.net/graphics/png/documents/>.

The PNG-1.0 specification is availableas RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as aW3C Recommendation <http://www.w3.org/TR/REC.png.html>. Someadditional chunks are described in the special-purpose public chunksdocuments at <ftp://ftp.uu.net/graphics/png/documents/>.

Other informationabout PNG, and the latest version of libpng, can be found at the PNG homepage, <http://www.libpng.org/pub/png/>and at <ftp://ftp.uu.net/graphics/png/>.

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, <http://www.info-zip.org/pub/infozip/zlib/>.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. Note: thread safety may be defeatedby use of some of the MMX assembler code in pnggccrd.c, which is onlycompiled when the user defines PNG_THREAD_UNSAFE_OK.

 

II. Structures

There are two main structures that are important to libpng, png_structand png_info. The first, png_struct, is an internal structure thatwill not, for the most part, be used by a user except as the firstvariable passed to every libpng function call.

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. The fields of png_info are still available forolder applications, but it is suggested that applications use the newinterfaces if at all possible.

Applications that do make direct access to the members of png_struct (exceptfor png_ptr->jmpbuf) must be recompiled whenever the library is updated,and applications that make direct access to the members of png_info mustbe 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, themembers of the png_info structure reverted to the old order, as they werein versions 0.97c through 1.0.5. Starting with version 2.0.0, bothstructures are going to be hidden, and the contents of the structures willonly 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>

 

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.

 

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, 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 if the bytes match the correspondingbytes of the PNG signature, or nonzero otherwise. Of course, the more bytesyou 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 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_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 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 jmpbuf field 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,
           &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 caseerrors 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 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);

 

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_ptr ptr,
         png_unknown_chunkp chunk);
    {
       /* The unknown chunk structure contains your
          chunk data: */
           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.  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 thatyou can retrieve with


    png_get_user_chunk_ptr(png_ptr);

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_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);

 

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; unknown chunks will be discarded. To changethis, you can call:


    png_set_keep_unknown_chunks(png_ptr, info_ptr, keep,
        chunk_list, num_chunks);
    keep       - 0: do not keep
                 1: keep only if safe-to-copy
                 2: keep even if unsafe-to-copy
    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

Unknown chunks declared in this way will be saved as raw data onto alist of png_unknown_chunk structures. If a chunk that is normallyknown to libpng is named in the list, it will be handled as unknown,according to the "keep" directive. If a chunk is named in successiveinstances of png_set_keep_unknown_chunks(), the final instance willtake precedence.

 

The high-level read interface

At this point there are two ways to proceed; through the high-levelread interface, or through a sequence of low-level read operations.You can use the high-level interface if (a) you are willing to readthe entire image into memory, and (b) the input transformationsyou 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 logical OR ofsome 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 pointto transformation parameters required by some future input transform.)

After you have called png_read_png(), you can retrieve the image datawith


   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 allocaterow_pointers prior to calling png_read_png() with


   row_pointers = png_malloc(png_ptr,
      height*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 definerow_pointers[i] to point into the proper places in your block.

If you use png_set_rows(), the application is responsible for freeingrow_pointers (and row_pointers[i], if they were separately allocated).

If you don't allocate row_pointers ahead of time, png_read_png() willdo it, and it'll be free'ed when you call png_destroy_*().

 

The low-level read interface

If you are going the low-level route, you are now ready to read allthe file information up to the actual image data. You do this with acall to png_read_info().


    png_read_info(png_ptr, info_ptr);

This will process all chunks up to but not including the image data.

 

Querying the info structure

Functions are used to get the information from the info_ptr once ithas been read. Note that these fields may not be completely filledin 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 chunkhas been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) andpng_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if thedata has been read, or zero if it is missing. The parameters to thepng_get_<chunk> are set directly if they are simple data types, or a pointerinto the info_ptr is returned for any complex types.


    png_get_PLTE(png_ptr, info_ptr, &palette,
                     &num_palette);
 &nb