Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libpng / 6e4184249c17953cec5c6374e66ab2b5bacefc3a / . / libpng.3
blob: aa44db438d77fa595209f0a84ad36d861f19ccc7 [file] [log] [blame]
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]1.TH LIBPNG 3 "December 30, 2011"
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]2.SH NAME
Glenn Randers-Pehrson67ee8ce2011-12-22 08:21:00 -0600[diff] [blame]3libpng \- Portable Network Graphics (PNG) Reference Library 1.6.0beta04
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4.SH SYNOPSIS
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]5\fB
6#include <png.h>\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]7
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]8\fBpng_uint_32 png_access_version_number \fI(void\fP\fB);\fP
9
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]10\fBvoid png_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
11
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]12\fBvoid png_build_grayscale_palette (int \fP\fIbit_depth\fP\fB, png_colorp \fIpalette\fP\fB);\fP
13
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]14\fBpng_voidp png_calloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
15
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]16\fBvoid png_chunk_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
17
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]18\fBvoid png_chunk_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]19
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]20\fBvoid png_chunk_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]21
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]22\fBvoid png_convert_from_struct_tm (png_timep \fP\fIptime\fP\fB, struct tm FAR * \fIttime\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]23
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]24\fBvoid png_convert_from_time_t (png_timep \fP\fIptime\fP\fB, time_t \fIttime\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]25
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]26\fBpng_charp png_convert_to_rfc1123 (png_structp \fP\fIpng_ptr\fP\fB, png_timep \fIptime\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]27
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]28\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]29
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]30\fBpng_structp png_create_read_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]31
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]32\fBpng_structp png_create_read_struct_2 (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]33
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]34\fBpng_structp png_create_write_struct (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarn_fn\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]35
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]36\fBpng_structp png_create_write_struct_2 (png_const_charp \fP\fIuser_png_ver\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fP\fIwarn_fn\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
37
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]38\fBvoid png_data_freer (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIfreer\fP\fB, png_uint_32 \fImask)\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]39
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]40\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
41
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]42\fBvoid png_destroy_read_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fP\fIinfo_ptr_ptr\fP\fB, png_infopp \fIend_info_ptr_ptr\fP\fB);\fP
43
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]44\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
45
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]46\fBvoid png_err (png_structp \fIpng_ptr\fP\fB);\fP
47
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]48\fBvoid png_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
49
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]50\fBvoid png_free (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
51
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]52\fBvoid png_free_chunk_list (png_structp \fIpng_ptr\fP\fB);\fP
53
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]54\fBvoid png_free_default (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]55
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]56\fBvoid png_free_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fInum\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]57
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]58\fBpng_byte png_get_bit_depth (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]59
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]60\fBpng_uint_32 png_get_bKGD (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]61
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]62\fBpng_byte png_get_channels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]63
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]64\fBpng_uint_32 png_get_cHRM (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]65
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]66\fBpng_uint_32 png_get_cHRM_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]67
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]68\fBpng_uint_32 png_get_cHRM_XYZ (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*red_X\fP\fB, double \fP\fI*red_Y\fP\fB, double \fP\fI*red_Z\fP\fB, double \fP\fI*green_X\fP\fB, double \fP\fI*green_Y\fP\fB, double \fP\fI*green_Z\fP\fB, double \fP\fI*blue_X\fP\fB, double \fP\fI*blue_Y\fP\fB, double \fI*blue_Z\fP\fB);\fP
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]69
John Bowler736f40f2011-08-25 16:19:44 -0500[diff] [blame]70\fBpng_uint_32 png_get_cHRM_XYZ_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_fixed_point \fP\fI*int_red_X\fP\fB, png_fixed_point \fP\fI*int_red_Y\fP\fB, png_fixed_point \fP\fI*int_red_Z\fP\fB, png_fixed_point \fP\fI*int_green_X\fP\fB, png_fixed_point \fP\fI*int_green_Y\fP\fB, png_fixed_point \fP\fI*int_green_Z\fP\fB, png_fixed_point \fP\fI*int_blue_X\fP\fB, png_fixed_point \fP\fI*int_blue_Y\fP\fB, png_fixed_point \fI*int_blue_Z\fP\fB);\fP
71
John Bowler736f40f2011-08-25 16:19:44 -0500[diff] [blame]72\fBpng_uint_32 png_get_chunk_cache_max (png_const_structp \fIpng_ptr\fP\fB);\fP
73
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]74\fBpng_alloc_size_t png_get_chunk_malloc_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]75
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]76\fBpng_byte png_get_color_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]77
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]78\fBpng_uint_32 png_get_compression_buffer_size (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]79
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]80\fBpng_byte png_get_compression_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]81
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]82\fBpng_byte png_get_copyright (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]83
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]84\fBpng_uint_32 png_get_current_row_number \fI(png_const_structp\fP\fB);\fP
85
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]86\fBpng_byte png_get_current_pass_number \fI(png_const_structp\fP\fB);\fP
87
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]88\fBpng_voidp png_get_error_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]89
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]90\fBpng_byte png_get_filter_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]91
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]92\fBpng_uint_32 png_get_gAMA (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]93
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]94\fBpng_uint_32 png_get_gAMA_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]95
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]96\fBpng_byte png_get_header_ver (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]97
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]98\fBpng_byte png_get_header_version (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]99
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]100\fBpng_uint_32 png_get_hIST (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]101
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]102\fBpng_uint_32 png_get_iCCP (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_bytepp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]103
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]104\fBpng_uint_32 png_get_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*width\fP\fB, png_uint_32 \fP\fI*height\fP\fB, int \fP\fI*bit_depth\fP\fB, int \fP\fI*color_type\fP\fB, int \fP\fI*interlace_type\fP\fB, int \fP\fI*compression_type\fP\fB, int \fI*filter_type\fP\fB);\fP
105
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]106\fBpng_uint_32 png_get_image_height (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]107
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]108\fBpng_uint_32 png_get_image_width (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]109
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]110\fBpng_int_32 png_get_int_32 (png_bytep \fIbuf\fP\fB);\fP
111
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]112\fBpng_byte png_get_interlace_type (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]113
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]114\fBpng_uint_32 png_get_io_chunk_type (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona63dbed2011-01-22 08:51:19 -0600[diff] [blame]115
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]116\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP
117
Glenn Randers-Pehrsona63dbed2011-01-22 08:51:19 -0600[diff] [blame]118\fBpng_uint_32 png_get_io_state (png_structp \fIpng_ptr\fP\fB);\fP
119
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]120\fBpng_byte png_get_libpng_ver (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]121
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]122\fBpng_voidp png_get_mem_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]123
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]124\fBpng_uint_32 png_get_oFFs (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]125
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]126\fBpng_uint_32 png_get_pCAL (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]127
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]128\fBpng_uint_32 png_get_pHYs (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]129
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]130\fBfloat png_get_pixel_aspect_ratio (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]131
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]132\fBpng_uint_32 png_get_pHYs_dpi (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]133
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]134\fBpng_fixed_point png_get_pixel_aspect_ratio_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]135
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]136\fBpng_uint_32 png_get_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]137
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]138\fBpng_uint_32 png_get_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]139
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]140\fBpng_voidp png_get_progressive_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]141
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]142\fBpng_uint_32 png_get_PLTE (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]143
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]144\fBpng_byte png_get_rgb_to_gray_status (png_const_structp png_ptr) png_uint_32 png_get_rowbytes (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]145
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]146\fBpng_bytepp png_get_rows (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]147
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]148\fBpng_uint_32 png_get_sBIT (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]149
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]150\fBvoid png_get_sCAL (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, double* \fP\fIwidth\fP\fB, double* \fIheight\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]151
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]152\fBvoid png_get_sCAL_fixed (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_fixed_pointp \fP\fIwidth\fP\fB, png_fixed_pointp \fIheight\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]153
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]154\fBvoid png_get_sCAL_s (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int* \fP\fIunit\fP\fB, png_charpp \fP\fIwidth\fP\fB, png_charpp \fIheight\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]155
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]156\fBpng_bytep png_get_signature (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]157
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]158\fBpng_uint_32 png_get_sPLT (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]159
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]160\fBpng_uint_32 png_get_sRGB (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, int \fI*file_srgb_intent\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]161
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]162\fBpng_uint_32 png_get_text (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]163
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]164\fBpng_uint_32 png_get_tIME (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]165
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]166\fBpng_uint_32 png_get_tRNS (png_const_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans_alpha\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_color\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]167
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]168\fB/* This function is really an inline macro. */ png_uint_16 png_get_uint_16 (png_bytep \fIbuf\fP\fB);\fP
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]169
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]170\fBpng_uint_32 png_get_uint_31 (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIbuf\fP\fB);\fP
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]171
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]172\fB/* This function is really an inline macro. */ png_uint_32 png_get_uint_32 (png_bytep \fIbuf\fP\fB);\fP
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]173
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]174\fBpng_uint_32 png_get_unknown_chunks (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]175
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]176\fBpng_voidp png_get_user_chunk_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]177
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]178\fBpng_uint_32 png_get_user_height_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]179
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]180\fBpng_voidp png_get_user_transform_ptr (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]181
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]182\fBpng_uint_32 png_get_user_width_max (png_const_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]183
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]184\fBpng_uint_32 png_get_valid (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]185
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]186\fBfloat png_get_x_offset_inches (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]187
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]188\fBpng_fixed_point png_get_x_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]189
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]190\fBpng_int_32 png_get_x_offset_microns (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]191
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]192\fBpng_int_32 png_get_x_offset_pixels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]193
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]194\fBpng_uint_32 png_get_x_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]195
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]196\fBpng_uint_32 png_get_x_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]197
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]198\fBfloat png_get_y_offset_inches (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]199
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]200\fBpng_fixed_point png_get_y_offset_inches_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]201
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]202\fBpng_int_32 png_get_y_offset_microns (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]203
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]204\fBpng_int_32 png_get_y_offset_pixels (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]205
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]206\fBpng_uint_32 png_get_y_pixels_per_inch (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]207
John Bowler0a5c9c02011-01-22 17:36:34 -0600[diff] [blame]208\fBpng_uint_32 png_get_y_pixels_per_meter (png_const_structp \fP\fIpng_ptr\fP\fB, png_const_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]209
Glenn Randers-Pehrsonc1bfe682002-03-06 22:08:00 -0600[diff] [blame]210\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP
211
Glenn Randers-Pehrsone0a6c062011-11-07 23:50:05 -0600[diff] [blame]212\fBint png_image_begin_read_from_file (png_imagep \fP\fIimage\fP\fB, const char \fI*file_name\fP\fB);\fP
213
Glenn Randers-Pehrsone0a6c062011-11-07 23:50:05 -0600[diff] [blame]214\fBint png_image_begin_read_from_stdio (png_imagep \fP\fIimage\fP\fB, FILE* \fIfile\fP\fB);\fP
215
Glenn Randers-Pehrsone0a6c062011-11-07 23:50:05 -0600[diff] [blame]216\fBint, png_image_begin_read_from_memory (png_imagep \fP\fIimage\fP\fB, png_const_voidp \fP\fImemory\fP\fB, png_size_t \fIsize\fP\fB);\fP
217
Glenn Randers-Pehrsone0a6c062011-11-07 23:50:05 -0600[diff] [blame]218\fBint png_image_finish_read (png_imagep \fP\fIimage\fP\fB, png_colorp \fP\fIbackground\fP\fB, void \fP\fI*buffer\fP\fB, png_int_32 \fIrow_stride\fP\fB);\fP
219
Glenn Randers-Pehrsone0a6c062011-11-07 23:50:05 -0600[diff] [blame]220\fBvoid png_image_free (png_imagep \fIimage\fP\fB);\fP
221
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]222\fBint png_image_write_to_file (png_imagep \fP\fIimage\fP\fB, const char \fP\fI*file\fP\fB, int \fP\fIconvert_to_8bit\fP\fB, const void \fP\fI*buffer\fP\fB, png_int_32 \fIrow_stride\fP\fB);\fP
Glenn Randers-Pehrsone0a6c062011-11-07 23:50:05 -0600[diff] [blame]223
224\fBint png_image_write_to_stdio (png_imagep \fP\fIimage\fP\fB, FILE \fP\fI*file\fP\fB, int \fP\fIconvert_to_8_bit\fP\fB, const void \fP\fI*buffer\fP\fB, png_int_32 \fIrow_stride)\fP\fB);\fP
225
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]226\fBvoid png_info_init_3 (png_infopp \fP\fIinfo_ptr\fP\fB, png_size_t \fIpng_info_struct_size\fP\fB);\fP
227
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]228\fBvoid png_init_io (png_structp \fP\fIpng_ptr\fP\fB, FILE \fI*fp\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]229
Glenn Randers-Pehrsonf98726a2010-02-19 09:54:53 -0600[diff] [blame]230\fBvoid png_longjmp (png_structp \fP\fIpng_ptr\fP\fB, int \fIval\fP\fB);\fP
231
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]232\fBpng_voidp png_malloc (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]233
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]234\fBpng_voidp png_malloc_default (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
235
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]236\fBpng_voidp png_malloc_warn (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
237
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]238\fBpng_uint_32 png_permit_mng_features (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fImng_features_permitted\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]239
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]240\fBvoid png_process_data (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fIbuffer\fP\fB, png_size_t \fIbuffer_size\fP\fB);\fP
241
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]242\fBpng_size_t png_process_data_pause \fP\fI(png_structp\fP\fB, int \fIsave\fP\fB);\fP
243
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]244\fBpng_uint_32 png_process_data_skip \fI(png_structp\fP\fB);\fP
245
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]246\fBvoid png_progressive_combine_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIold_row\fP\fB, png_bytep \fInew_row\fP\fB);\fP
247
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]248\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
249
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]250\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
251
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]252\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
253
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]254\fBvoid png_read_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]255
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]256\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
257
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]258\fBvoid png_read_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_bytepp \fP\fIdisplay_row\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
259
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]260\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
261
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]262\fBint png_reset_zstream (png_structp \fIpng_ptr\fP\fB);\fP
263
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]264\fBvoid png_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]265
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]266\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP
267
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]268\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP
269
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]270\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int flags); void png_set_alpha_mode (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, double output_gamma); void png_set_alpha_mode_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImode\fP\fB, png_fixed_point \fIoutput_gamma\fP\fB);\fP
Glenn Randers-Pehrsonc7822512011-05-07 21:23:43 -0500[diff] [blame]271
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]272\fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP
273
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]274\fBvoid png_set_background_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, png_uint_32 \fIbackground_gamma\fP\fB);\fP
275
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]276\fBvoid png_set_benign_errors (png_structp \fP\fIpng_ptr\fP\fB, int \fIallowed\fP\fB);\fP
277
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]278\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP
279
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]280\fBvoid png_set_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fIbackground\fP\fB);\fP
281
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]282\fBvoid png_set_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIwhite_x\fP\fB, double \fP\fIwhite_y\fP\fB, double \fP\fIred_x\fP\fB, double \fP\fIred_y\fP\fB, double \fP\fIgreen_x\fP\fB, double \fP\fIgreen_y\fP\fB, double \fP\fIblue_x\fP\fB, double \fIblue_y\fP\fB);\fP
283
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]284\fBvoid png_set_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwhite_x\fP\fB, png_uint_32 \fP\fIwhite_y\fP\fB, png_uint_32 \fP\fIred_x\fP\fB, png_uint_32 \fP\fIred_y\fP\fB, png_uint_32 \fP\fIgreen_x\fP\fB, png_uint_32 \fP\fIgreen_y\fP\fB, png_uint_32 \fP\fIblue_x\fP\fB, png_uint_32 \fIblue_y\fP\fB);\fP
285
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]286\fBvoid png_set_cHRM_XYZ (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fIred_X\fP\fB, double \fP\fIred_Y\fP\fB, double \fP\fIred_Z\fP\fB, double \fP\fIgreen_X\fP\fB, double \fP\fIgreen_Y\fP\fB, double \fP\fIgreen_Z\fP\fB, double \fP\fIblue_X\fP\fB, double \fP\fIblue_Y\fP\fB, double \fIblue_Z\fP\fB);\fP
John Bowler736f40f2011-08-25 16:19:44 -0500[diff] [blame]287
288\fBvoid png_set_cHRM_XYZ_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_fixed_point \fP\fIint_red_X\fP\fB, png_fixed_point \fP\fIint_red_Y\fP\fB, png_fixed_point \fP\fIint_red_Z\fP\fB, png_fixed_point \fP\fIint_green_X\fP\fB, png_fixed_point \fP\fIint_green_Y\fP\fB, png_fixed_point \fP\fIint_green_Z\fP\fB, png_fixed_point \fP\fIint_blue_X\fP\fB, png_fixed_point \fP\fIint_blue_Y\fP\fB, png_fixed_point \fIint_blue_Z\fP\fB);\fP
289
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]290\fBvoid png_set_chunk_cache_max (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIuser_chunk_cache_max\fP\fB);\fP
291
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]292\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
293
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]294\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
295
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]296\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP
297
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]298\fBvoid png_set_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]299
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]300\fBvoid png_set_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]301
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]302\fBvoid png_set_crc_action (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIcrit_action\fP\fB, int \fIancil_action\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]303
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]304\fBvoid png_set_error_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIerror_ptr\fP\fB, png_error_ptr \fP\fIerror_fn\fP\fB, png_error_ptr \fIwarning_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]305
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]306\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsonc85f5f62011-02-13 05:56:07 -0600[diff] [blame]307
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]308\fBvoid png_set_expand_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]309
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]310\fBvoid png_set_expand_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]311
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]312\fBvoid png_set_filler (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]313
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]314\fBvoid png_set_filter (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fImethod\fP\fB, int \fIfilters\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]315
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]316\fBvoid png_set_filter_heuristics (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_doublep \fP\fIfilter_weights\fP\fB, png_doublep \fIfilter_costs\fP\fB);\fP
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]317
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]318\fBvoid png_set_filter_heuristics_fixed (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIheuristic_method\fP\fB, int \fP\fInum_weights\fP\fB, png_fixed_point_p \fP\fIfilter_weights\fP\fB, png_fixed_point_p \fIfilter_costs\fP\fB);\fP
319
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]320\fBvoid png_set_flush (png_structp \fP\fIpng_ptr\fP\fB, int \fInrows\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]321
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]322\fBvoid png_set_gamma (png_structp \fP\fIpng_ptr\fP\fB, double \fP\fIscreen_gamma\fP\fB, double \fIdefault_file_gamma\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]323
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]324\fBvoid png_set_gamma_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIscreen_gamma\fP\fB, png_uint_32 default_file_gamma); void png_set_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fIfile_gamma\fP\fB);\fP
Glenn Randers-Pehrsonad81d712009-07-30 15:39:00 -0500[diff] [blame]325
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]326\fBvoid png_set_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIfile_gamma\fP\fB);\fP
327
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]328\fBvoid png_set_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]329
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]330\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]331
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]332\fBvoid png_set_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fIhist\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]333
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]334\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_const_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_const_bytep \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]335
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]336\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]337
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]338\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP
339
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]340\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]341
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]342\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]343
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]344\fBvoid png_set_IHDR (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIwidth\fP\fB, png_uint_32 \fP\fIheight\fP\fB, int \fP\fIbit_depth\fP\fB, int \fP\fIcolor_type\fP\fB, int \fP\fIinterlace_type\fP\fB, int \fP\fIcompression_type\fP\fB, int \fIfilter_type\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]345
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]346\fBvoid png_set_keep_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIkeep\fP\fB, png_bytep \fP\fIchunk_list\fP\fB, int \fInum_chunks\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]347
Glenn Randers-Pehrson1e6ed732009-11-20 22:06:56 -0600[diff] [blame]348\fBjmp_buf* png_set_longjmp_fn (png_structp \fP\fIpng_ptr\fP\fB, png_longjmp_ptr \fP\fIlongjmp_fn\fP\fB, size_t \fIjmp_buf_size\fP\fB);\fP
349
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]350\fBvoid png_set_chunk_malloc_max (png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIuser_chunk_cache_max\fP\fB);\fP
351
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]352\fBvoid png_set_compression_buffer_size (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
353
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]354\fBvoid png_set_mem_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fImem_ptr\fP\fB, png_malloc_ptr \fP\fImalloc_fn\fP\fB, png_free_ptr \fIfree_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]355
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]356\fBvoid png_set_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIoffset_x\fP\fB, png_uint_32 \fP\fIoffset_y\fP\fB, int \fIunit_type\fP\fB);\fP
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]357
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]358\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]359
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]360\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]361
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]362\fBvoid png_set_palette_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]363
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]364\fBvoid png_set_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIpurpose\fP\fB, png_int_32 \fP\fIX0\fP\fB, png_int_32 \fP\fIX1\fP\fB, int \fP\fItype\fP\fB, int \fP\fInparams\fP\fB, png_charp \fP\fIunits\fP\fB, png_charpp \fIparams\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]365
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]366\fBvoid png_set_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fIres_x\fP\fB, png_uint_32 \fP\fIres_y\fP\fB, int \fIunit_type\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]367
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]368\fBvoid png_set_progressive_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIprogressive_ptr\fP\fB, png_progressive_info_ptr \fP\fIinfo_fn\fP\fB, png_progressive_row_ptr \fP\fIrow_fn\fP\fB, png_progressive_end_ptr \fIend_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]369
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]370\fBvoid png_set_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fInum_palette\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]371
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]372\fBvoid png_set_quantize (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_quantize\fP\fB);\fP
373
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]374\fBvoid png_set_read_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fIread_data_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]375
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]376\fBvoid png_set_read_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_read_status_ptr \fIread_row_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]377
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]378\fBvoid png_set_read_user_chunk_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_chunk_ptr\fP\fB, png_user_chunk_ptr \fIread_user_chunk_fn\fP\fB);\fP
379
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]380\fBvoid png_set_read_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIread_user_transform_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]381
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]382\fBvoid png_set_rgb_to_gray (png_structp \fP\fIpng_ptr\fP\fB, int \fP\fIerror_action\fP\fB, double \fP\fIred\fP\fB, double \fIgreen\fP\fB);\fP
383
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]384\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_uint_32 \fP\fIred\fP\fB, png_uint_32 \fIgreen\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]385
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]386\fBvoid png_set_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytepp \fIrow_pointers\fP\fB);\fP
387
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]388\fBvoid png_set_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fIsig_bit\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]389
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]390\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP
391
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]392\fBvoid png_set_sCAL_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_fixed_point \fP\fIwidth\fP\fB, png_fixed_point \fIheight\fP\fB);\fP
393
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]394\fBvoid png_set_sCAL_s (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIunit\fP\fB, png_charp \fP\fIwidth\fP\fB, png_charp height); void png_set_scale_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsonc4a82142011-06-18 00:44:08 -0500[diff] [blame]395
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]396\fBvoid png_set_shift (png_structp \fP\fIpng_ptr\fP\fB, png_color_8p \fItrue_bits\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]397
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]398\fBvoid png_set_sig_bytes (png_structp \fP\fIpng_ptr\fP\fB, int \fInum_bytes\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]399
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]400\fBvoid png_set_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fP\fIsplt_ptr\fP\fB, int \fInum_spalettes\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]401
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]402\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIsrgb_intent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]403
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]404\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIsrgb_intent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]405
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]406\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]407
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]408\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]409
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]410\fBvoid png_set_strip_error_numbers (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIstrip_mode\fP\fB);\fP
411
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]412\fBvoid png_set_swap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]413
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]414\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]415
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]416\fBvoid png_set_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fItext_ptr\fP\fB, int \fInum_text\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]417
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]418\fBvoid png_set_text_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
419
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]420\fBvoid png_set_text_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
421
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]422\fBvoid png_set_text_compression_strategy (png_structp \fP\fIpng_ptr\fP\fB, int \fIstrategy\fP\fB);\fP
423
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]424\fBvoid png_set_text_compression_window_bits (png_structp \fP\fIpng_ptr\fP\fB, int \fIwindow_bits\fP\fB);\fP
425
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]426\fBvoid \fP\fIpng_set_text_compression_method\fP\fB, (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod)\fP\fB);\fP
427
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]428\fBvoid png_set_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fImod_time\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]429
Glenn Randers-Pehrsonf3c51e42011-01-15 10:25:25 -0600[diff] [blame]430\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans_alpha\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_color\fP\fB);\fP
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]431
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]432\fBvoid png_set_tRNS_to_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]433
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]434\fBpng_uint_32 png_set_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkp \fP\fIunknowns\fP\fB, int \fP\fInum\fP\fB, int \fIlocation\fP\fB);\fP
435
Glenn Randers-Pehrsonbb98bcb2011-01-22 16:27:39 -0600[diff] [blame]436\fBvoid png_set_unknown_chunk_location (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fIchunk\fP\fB, int \fIlocation\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]437
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]438\fBvoid png_set_user_limits (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIuser_width_max\fP\fB, png_uint_32 \fIuser_height_max\fP\fB);\fP
439
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]440\fBvoid png_set_user_transform_info (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIuser_transform_ptr\fP\fB, int \fP\fIuser_transform_depth\fP\fB, int \fIuser_transform_channels\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]441
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]442\fBvoid png_set_write_fn (png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fP\fIio_ptr\fP\fB, png_rw_ptr \fP\fIwrite_data_fn\fP\fB, png_flush_ptr \fIoutput_flush_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]443
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]444\fBvoid png_set_write_status_fn (png_structp \fP\fIpng_ptr\fP\fB, png_write_status_ptr \fIwrite_row_fn\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]445
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]446\fBvoid png_set_write_user_transform_fn (png_structp \fP\fIpng_ptr\fP\fB, png_user_transform_ptr \fIwrite_user_transform_fn\fP\fB);\fP
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]447
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]448\fBint png_sig_cmp (png_bytep \fP\fIsig\fP\fB, png_size_t \fP\fIstart\fP\fB, png_size_t \fInum_to_check\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]449
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]450\fBvoid png_start_read_image (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]451
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]452\fBvoid png_warning (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fImessage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]453
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]454\fBvoid png_write_chunk (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]455
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]456\fBvoid png_write_chunk_data (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIdata\fP\fB, png_size_t \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]457
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]458\fBvoid png_write_chunk_end (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]459
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]460\fBvoid png_write_chunk_start (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIchunk_name\fP\fB, png_uint_32 \fIlength\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]461
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]462\fBvoid png_write_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]463
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]464\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]465
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]466\fBvoid png_write_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]467
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]468\fBvoid png_write_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]469
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]470\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
471
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]472\fBvoid png_write_png (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fP\fItransforms\fP\fB, png_voidp \fIparams\fP\fB);\fP
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]473
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]474\fBvoid png_write_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIrow\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]475
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]476\fBvoid png_write_rows (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fP\fIrow\fP\fB, png_uint_32 \fInum_rows\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]477
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]478\fBvoid png_write_sig (png_structp \fIpng_ptr\fP\fB);\fP
479
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]480\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP
481
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]482\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP
483
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]484.SH DESCRIPTION
485The
486.I libpng
487library supports encoding, decoding, and various manipulations of
488the Portable Network Graphics (PNG) format image files. It uses the
489.IR zlib(3)
490compression library.
Glenn Randers-Pehrson557b2562010-10-17 12:55:04 -0500[diff] [blame]491Following is a copy of the libpng-manual.txt file that accompanies libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]492.SH LIBPNG.TXT
Glenn Randers-Pehrson557b2562010-10-17 12:55:04 -0500[diff] [blame]493libpng-manual.txt - A description on how to use and modify libpng
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]494
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]495 libpng version 1.6.0beta04 - December 30, 2011
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]496 Updated and distributed by Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]497 <glennrp at users.sourceforge.net>
Glenn Randers-Pehrson9f45c8e2011-01-15 19:35:03 -0600[diff] [blame]498 Copyright (c) 1998-2011 Glenn Randers-Pehrson
Glenn Randers-Pehrson037023b2009-06-24 10:27:36 -0500[diff] [blame]499
Glenn Randers-Pehrsonbfbf8652009-06-26 21:46:52 -0500[diff] [blame]500 This document is released under the libpng license.
Glenn Randers-Pehrsonc332bbc2009-06-25 13:43:50 -0500[diff] [blame]501 For conditions of distribution and use, see the disclaimer
Glenn Randers-Pehrson037023b2009-06-24 10:27:36 -0500[diff] [blame]502 and license in png.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]503
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]504 Based on:
505
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]506 libpng versions 0.97, January 1998, through 1.6.0beta04 - December 30, 2011
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]507 Updated and distributed by Glenn Randers-Pehrson
Glenn Randers-Pehrson9f45c8e2011-01-15 19:35:03 -0600[diff] [blame]508 Copyright (c) 1998-2011 Glenn Randers-Pehrson
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]509
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]510 libpng 1.0 beta 6 version 0.96 May 28, 1997
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]511 Updated and distributed by Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]512 Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]513
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]514 libpng 1.0 beta 2 - version 0.88 January 26, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]515 For conditions of distribution and use, see copyright
516 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]517 Schalnat, Group 42, Inc.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]518
519 Updated/rewritten per request in the libpng FAQ
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]520 Copyright (c) 1995, 1996 Frank J. T. Wojcik
521 December 18, 1995 & January 20, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]522
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]523 TABLE OF CONTENTS
524
525 I. Introduction
526 II. Structures
527 III. Reading
528 IV. Writing
529 V. Modifying/Customizing libpng
530 VI. MNG support
531 VII. Changes to Libpng from version 0.88
532 VIII. Changes to Libpng from version 1.0.x to 1.2.x
533 IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
534 X. Changes to Libpng from version 1.4.x to 1.5.x
535 XI. Changes to Libpng from version 1.5.x to 1.6.x
536 XII. Detecting libpng
537 XIII. Source code repository
538 XIV. Coding style
539 XV. Y2K Compliance in libpng
540
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]541.SH I. Introduction
542
543This file describes how to use and modify the PNG reference library
544(known as libpng) for your own use. There are five sections to this
545file: introduction, structures, reading, writing, and modification and
546configuration notes for various special platforms. In addition to this
547file, example.c is a good starting point for using the library, as
548it is heavily commented and should include everything most people
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]549will need. We assume that libpng is already installed; see the
550INSTALL file for instructions on how to install libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]551
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]552For examples of libpng usage, see the files "example.c", "pngtest.c",
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]553and the files in the "contrib" directory, all of which are included in
554the libpng distribution.
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]555
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]556Libpng was written as a companion to the PNG specification, as a way
557of reducing the amount of time and effort it takes to support the PNG
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]558file format in application programs.
559
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]560The PNG specification (second edition), November 2003, is available as
561a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
562<http://www.w3.org/TR/2003/REC-PNG-20031110/
563The W3C and ISO documents have identical technical content.
564
565The PNG-1.2 specification is available at
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]566<http://www.libpng.org/pub/png/documents/>. It is technically equivalent
567to the PNG specification (second edition) but has some additional material.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]568
569The PNG-1.0 specification is available
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]570as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]571W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
572
573Some additional chunks are described in the special-purpose public chunks
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]574documents at <http://www.libpng.org/pub/png/documents/>.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]575
576Other information
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]577about PNG, and the latest version of libpng, can be found at the PNG home
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]578page, <http://www.libpng.org/pub/png/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]579
580Most users will not have to modify the library significantly; advanced
581users may want to modify it more. All attempts were made to make it as
582complete as possible, while keeping the code easy to understand.
583Currently, this library only supports C. Support for other languages
584is being considered.
585
586Libpng has been designed to handle multiple sessions at one time,
587to be easily modifiable, to be portable to the vast majority of
588machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
589to use. The ultimate goal of libpng is to promote the acceptance of
590the PNG file format in whatever way possible. While there is still
591work to be done (see the TODO file), libpng should cover the
592majority of the needs of its users.
593
594Libpng uses zlib for its compression and decompression of PNG files.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]595Further information about zlib, and the latest version of zlib, can
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]596be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]597The zlib compression utility is a general purpose utility that is
598useful for more than PNG files, and can be used without libpng.
599See the documentation delivered with zlib for more details.
600You can usually find the source files for the zlib utility wherever you
601find the libpng source files.
602
603Libpng is thread safe, provided the threads are using different
604instances of the structures. Each thread should have its own
605png_struct and png_info instances, and thus its own image.
606Libpng does not protect itself against two threads using the
Glenn Randers-Pehrson56f63962008-10-06 10:16:17 -0500[diff] [blame]607same instance of a structure.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]608
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]609.SH II. Structures
610
611There are two main structures that are important to libpng, png_struct
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]612and png_info. Both are internal structures that are no longer exposed
613in the libpng interface (as of libpng 1.5.0).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]614
615The png_info structure is designed to provide information about the
616PNG file. At one time, the fields of png_info were intended to be
617directly accessible to the user. However, this tended to cause problems
618with applications using dynamically loaded libraries, and as a result
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]619a set of interface functions for png_info (the png_get_*() and png_set_*()
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]620functions) was developed, and direct access to the png_info fields was
621deprecated..
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]622
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]623The png_struct structure is the object used by the library to decode a
624single image. As of 1.5.0 this structure is also not exposed.
625
626Almost all libpng APIs require a pointer to a png_struct as the first argument.
627Many (in particular the png_set and png_get APIs) also require a pointer
628to png_info as the second argument. Some application visible macros
629defined in png.h designed for basic data access (reading and writing
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]630integers in the PNG format) don't take a png_info pointer, but it's almost
631always safe to assume that a (png_struct*) has to be passed to call an API
632function.
633
634You can have more than one png_info structure associated with an image,
635as illustrated in pngtest.c, one for information valid prior to the
636IDAT chunks and another (called "end_info" below) for things after them.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]637
638The png.h header file is an invaluable reference for programming with libpng.
639And while I'm on the topic, make sure you include the libpng header file:
640
641#include <png.h>
642
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]643and also (as of libpng-1.5.0) the zlib header file, if you need it:
644
645#include <zlib.h>
646
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]647.SS Types
648
649The png.h header file defines a number of integral types used by the
650APIs. Most of these are fairly obvious; for example types corresponding
651to integers of particular sizes and types for passing color values.
652
653One exception is how non-integral numbers are handled. For application
654convenience most APIs that take such numbers have C (double) arguments,
655however internally PNG, and libpng, use 32 bit signed integers and encode
656the value by multiplying by 100,000. As of libpng 1.5.0 a convenience
657macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
658which is simply (png_int_32).
659
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]660All APIs that take (double) arguments also have a matching API that
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]661takes the corresponding fixed point integer arguments. The fixed point
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]662API has the same name as the floating point one with "_fixed" appended.
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]663The actual range of values permitted in the APIs is frequently less than
664the full range of (png_fixed_point) (-21474 to +21474). When APIs require
665a non-negative argument the type is recorded as png_uint_32 above. Consult
666the header file and the text below for more information.
667
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]668Special care must be take with sCAL chunk handling because the chunk itself
669uses non-integral values encoded as strings containing decimal floating point
670numbers. See the comments in the header file.
671
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]672.SS Configuration
673
674The main header file function declarations are frequently protected by C
675preprocessing directives of the form:
676
677 #ifdef PNG_feature_SUPPORTED
678 declare-function
679 #endif
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]680 ...
681 #ifdef PNG_feature_SUPPORTED
682 use-function
683 #endif
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]684
685The library can be built without support for these APIs, although a
686standard build will have all implemented APIs. Application programs
687should check the feature macros before using an API for maximum
688portability. From libpng 1.5.0 the feature macros set during the build
689of libpng are recorded in the header file "pnglibconf.h" and this file
690is always included by png.h.
691
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]692If you don't need to change the library configuration from the default, skip to
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]693the next section ("Reading").
694
695Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
696of the build project files in the 'projects' directory simply copy
697scripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these build
698systems do not permit easy auto-configuration of the library - they only
699support the default configuration.
700
701The easiest way to make minor changes to the libpng configuration when
702auto-configuration is supported is to add definitions to the command line
703using (typically) CPPFLAGS. For example:
704
705CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
706
707will change the internal libpng math implementation for gamma correction and
708other arithmetic calculations to fixed point, avoiding the need for fast
709floating point support. The result can be seen in the generated pnglibconf.h -
710make sure it contains the changed feature macro setting.
711
712If you need to make more extensive configuration changes - more than one or two
713feature macro settings - you can either add -DPNG_USER_CONFIG to the build
714command line and put a list of feature macro settings in pngusr.h or you can set
715DFA_XTRA (a makefile variable) to a file containing the same information in the
716form of 'option' settings.
717
718A. Changing pnglibconf.h
719
720A variety of methods exist to build libpng. Not all of these support
721reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be
722rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
723
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]724Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
725pnglibconf.h and changing the lines defining the supported features, paying
726very close attention to the 'option' information in scripts/pnglibconf.dfa
727that describes those features and their requirements. This is easy to get
728wrong.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]729
730B. Configuration using DFA_XTRA
731
732Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
733variant such as 'nawk' or 'gawk', is available. The configure build will
734automatically find an appropriate awk and build pnglibconf.h.
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]735The scripts/pnglibconf.mak file contains a set of make rules for doing the
736same thing if configure is not used, and many of the makefiles in the scripts
737directory use this approach.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]738
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]739When rebuilding simply write a new file containing changed options and set
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]740DFA_XTRA to the name of this file. This causes the build to append the new file
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]741to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines
742of the following forms:
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]743
744everything = off
745
746This turns all optional features off. Include it at the start of pngusr.dfa to
747make it easier to build a minimal configuration. You will need to turn at least
748some features on afterward to enable either reading or writing code, or both.
749
750option feature on
751option feature off
752
753Enable or disable a single feature. This will automatically enable other
754features required by a feature that is turned on or disable other features that
755require a feature which is turned off. Conflicting settings will cause an error
756message to be emitted by awk.
757
758setting feature default value
759
760Changes the default value of setting 'feature' to 'value'. There are a small
761number of settings listed at the top of pnglibconf.h, they are documented in the
762source code. Most of these values have performance implications for the library
763but most of them have no visible effect on the API. Some can also be overridden
764from the API.
765
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]766This method of building a customized pnglibconf.h is illustrated in
767contrib/pngminim/*. See the "$(PNGCONF):" target in the makefile and
768pngusr.dfa in these directories.
769
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]770C. Configuration using PNG_USR_CONFIG
771
772If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
773pngusr.h will automatically be included before the options in
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]774scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only
775macro definitions turning features on or off or setting settings.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]776
777Apart from the global setting "everything = off" all the options listed above
778can be set using macros in pngusr.h:
779
780#define PNG_feature_SUPPORTED
781
782is equivalent to:
783
784option feature on
785
786#define PNG_NO_feature
787
788is equivalent to:
789
790option feature off
791
792#define PNG_feature value
793
794is equivalent to:
795
796setting feature default value
797
798Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
799pngusr file you supply override the contents of scripts/pnglibconf.dfa
800
801If confusing or incomprehensible behavior results it is possible to
802examine the intermediate file pnglibconf.dfn to find the full set of
803dependency information for each setting and option. Simply locate the
804feature in the file and read the C comments that precede it.
805
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]806This method is also illustrated in the contrib/pngminim/* makefiles and
807pngusr.h.
808
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]809.SH III. Reading
810
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]811We'll now walk you through the possible functions to call when reading
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]812in a PNG file sequentially, briefly explaining the syntax and purpose
813of each one. See example.c and png.h for more detail. While
814progressive reading is covered in the next section, you will still
815need some of the functions discussed in this section to read a PNG
816file.
817
818.SS Setup
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]819
820You will want to do the I/O initialization(*) before you get into libpng,
821so if it doesn't work, you don't have much to undo. Of course, you
822will also want to insure that you are, in fact, dealing with a PNG
823file. Libpng provides a simple check to see if a file is a PNG file.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]824To use it, pass in the first 1 to 8 bytes of the file to the function
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]825png_sig_cmp(), and it will return 0 (false) if the bytes match the
826corresponding bytes of the PNG signature, or nonzero (true) otherwise.
827Of course, the more bytes you pass in, the greater the accuracy of the
828prediction.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]829
830If you are intending to keep the file pointer open for use in libpng,
831you must ensure you don't read more than 8 bytes from the beginning
832of the file, and you also have to make a call to png_set_sig_bytes_read()
833with the number of bytes you read from the beginning. Libpng will
834then only check the bytes (if any) that your program didn't read.
835
836(*): If you are not using the standard I/O functions, you will need
837to replace them with custom functions. See the discussion under
838Customizing libpng.
839
840
841 FILE *fp = fopen(file_name, "rb");
842 if (!fp)
843 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]844 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]845 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]846
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]847 fread(header, 1, number, fp);
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]848 is_png = !png_sig_cmp(header, 0, number);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]849
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]850 if (!is_png)
851 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]852 return (NOT_PNG);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]853 }
854
855
856Next, png_struct and png_info need to be allocated and initialized. In
857order to ensure that the size of these structures is correct even with a
858dynamically linked libpng, there are functions to initialize and
859allocate the structures. We also pass the library version, optional
860pointers to error handling functions, and a pointer to a data struct for
861use by the error functions, if necessary (the pointer and functions can
862be NULL if the default error handlers are to be used). See the section
863on Changes to Libpng below regarding the old initialization functions.
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]864The structure allocation functions quietly return NULL if they fail to
865create the structure, so your application should check for that.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]866
867 png_structp png_ptr = png_create_read_struct
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]868 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]869 user_error_fn, user_warning_fn);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]870
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]871 if (!png_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]872 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]873
874 png_infop info_ptr = png_create_info_struct(png_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]875
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]876 if (!info_ptr)
877 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]878 png_destroy_read_struct(&png_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]879 (png_infopp)NULL, (png_infopp)NULL);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]880 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]881 }
882
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]883If you want to use your own memory allocation routines,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]884use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]885png_create_read_struct_2() instead of png_create_read_struct():
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]886
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]887 png_structp png_ptr = png_create_read_struct_2
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]888 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]889 user_error_fn, user_warning_fn, (png_voidp)
890 user_mem_ptr, user_malloc_fn, user_free_fn);
891
892The error handling routines passed to png_create_read_struct()
893and the memory alloc/free routines passed to png_create_struct_2()
894are only necessary if you are not using the libpng supplied error
895handling and memory alloc/free functions.
896
897When libpng encounters an error, it expects to longjmp back
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]898to your routine. Therefore, you will need to call setjmp and pass
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]899your png_jmpbuf(png_ptr). If you read the file from different
John Bowlere6dc85b2011-04-27 14:47:15 -0500[diff] [blame]900routines, you will need to update the longjmp buffer every time you enter
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]901a new routine that will call a png_*() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]902
903See your documentation of setjmp/longjmp for your compiler for more
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]904information on setjmp/longjmp. See the discussion on libpng error
905handling in the Customizing Libpng section below for more information
906on the libpng error handling. If an error occurs, and libpng longjmp's
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]907back to your setjmp, you will want to call png_destroy_read_struct() to
908free any memory.
909
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]910 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]911 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]912 png_destroy_read_struct(&png_ptr, &info_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]913 &end_info);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]914 fclose(fp);
915 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]916 }
917
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]918Pass (png_infopp)NULL instead of &end_info if you didn't create
919an end_info structure.
920
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]921If you would rather avoid the complexity of setjmp/longjmp issues,
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]922you can compile libpng with PNG_NO_SETJMP, in which case
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]923errors will result in a call to PNG_ABORT() which defaults to abort().
924
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]925You can #define PNG_ABORT() to a function that does something
926more useful than abort(), as long as your function does not
927return.
928
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]929Now you need to set up the input code. The default for libpng is to
930use the C function fread(). If you use this, you will need to pass a
931valid FILE * in the function png_init_io(). Be sure that the file is
932opened in binary mode. If you wish to handle reading data in another
933way, you need not call the png_init_io() function, but you must then
934implement the libpng I/O methods discussed in the Customizing Libpng
935section below.
936
937 png_init_io(png_ptr, fp);
938
939If you had previously opened the file and read any of the signature from
940the beginning in order to see if this was a PNG file, you need to let
941libpng know that there are some bytes missing from the start of the file.
942
943 png_set_sig_bytes(png_ptr, number);
944
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]945You can change the zlib compression buffer size to be used while
946reading compressed data with
947
948 png_set_compression_buffer_size(png_ptr, buffer_size);
949
950where the default size is 8192 bytes. Note that the buffer size
951is changed immediately and the buffer is reallocated immediately,
952instead of setting a flag to be acted upon later.
953
Glenn Randers-Pehrson9dd1cdf2011-01-06 21:42:36 -0600[diff] [blame]954If you want CRC errors to be handled in a different manner than
955the default, use
956
957 png_set_crc_action(png_ptr, crit_action, ancil_action);
958
959The values for png_set_crc_action() say how libpng is to handle CRC errors in
960ancillary and critical chunks, and whether to use the data contained
961therein. Note that it is impossible to "discard" data in a critical
962chunk.
963
964Choices for (int) crit_action are
965 PNG_CRC_DEFAULT 0 error/quit
966 PNG_CRC_ERROR_QUIT 1 error/quit
967 PNG_CRC_WARN_USE 3 warn/use data
968 PNG_CRC_QUIET_USE 4 quiet/use data
969 PNG_CRC_NO_CHANGE 5 use the current value
970
971Choices for (int) ancil_action are
972 PNG_CRC_DEFAULT 0 error/quit
973 PNG_CRC_ERROR_QUIT 1 error/quit
974 PNG_CRC_WARN_DISCARD 2 warn/discard data
975 PNG_CRC_WARN_USE 3 warn/use data
976 PNG_CRC_QUIET_USE 4 quiet/use data
977 PNG_CRC_NO_CHANGE 5 use the current value
978
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]979.SS Setting up callback code
980
981You can set up a callback function to handle any unknown chunks in the
982input stream. You must supply the function
983
Glenn Randers-Pehrson81ce8892011-01-24 08:04:37 -0600[diff] [blame]984 read_chunk_callback(png_structp png_ptr,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]985 png_unknown_chunkp chunk);
986 {
987 /* The unknown chunk structure contains your
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]988 chunk data, along with similar data for any other
989 unknown chunks: */
990
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]991 png_byte name[5];
992 png_byte *data;
993 png_size_t size;
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]994
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]995 /* Note that libpng has already taken care of
996 the CRC handling */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]997
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]998 /* put your code here. Search for your chunk in the
999 unknown chunk structure, process it, and return one
1000 of the following: */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1001
1002 return (-n); /* chunk had an error */
1003 return (0); /* did not recognize */
1004 return (n); /* success */
1005 }
1006
1007(You can give your function another name that you like instead of
1008"read_chunk_callback")
1009
1010To inform libpng about your function, use
1011
1012 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
1013 read_chunk_callback);
1014
1015This names not only the callback function, but also a user pointer that
1016you can retrieve with
1017
1018 png_get_user_chunk_ptr(png_ptr);
1019
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1020If you call the png_set_read_user_chunk_fn() function, then all unknown
1021chunks will be saved when read, in case your callback function will need
1022one or more of them. This behavior can be changed with the
1023png_set_keep_unknown_chunks() function, described below.
1024
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1025At this point, you can set up a callback function that will be
1026called after each row has been read, which you can use to control
1027a progress meter or the like. It's demonstrated in pngtest.c.
1028You must supply a function
1029
Glenn Randers-Pehrson81ce8892011-01-24 08:04:37 -0600[diff] [blame]1030 void read_row_callback(png_structp png_ptr,
1031 png_uint_32 row, int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1032 {
1033 /* put your code here */
1034 }
1035
1036(You can give it another name that you like instead of "read_row_callback")
1037
1038To inform libpng about your function, use
1039
1040 png_set_read_status_fn(png_ptr, read_row_callback);
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1041
John Bowler59010e52011-02-16 06:16:31 -0600[diff] [blame]1042When this function is called the row has already been completely processed and
1043the 'row' and 'pass' refer to the next row to be handled. For the
1044non-interlaced case the row that was just handled is simply one less than the
1045passed in row number, and pass will always be 0. For the interlaced case the
1046same applies unless the row value is 0, in which case the row just handled was
1047the last one from one of the preceding passes. Because interlacing may skip a
1048pass you cannot be sure that the preceding pass is just 'pass-1', if you really
1049need to know what the last pass is record (row,pass) from the callback and use
1050the last recorded value each time.
1051
1052As with the user transform you can find the output row using the
1053PNG_ROW_FROM_PASS_ROW macro.
1054
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1055.SS Unknown-chunk handling
1056
1057Now you get to set the way the library processes unknown chunks in the
1058input PNG stream. Both known and unknown chunks will be read. Normal
1059behavior is that known chunks will be parsed into information in
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1060various info_ptr members while unknown chunks will be discarded. This
1061behavior can be wasteful if your application will never use some known
1062chunk types. To change this, you can call:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1063
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]1064 png_set_keep_unknown_chunks(png_ptr, keep,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1065 chunk_list, num_chunks);
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1066 keep - 0: default unknown chunk handling
1067 1: ignore; do not keep
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1068 2: keep only if safe-to-copy
1069 3: keep even if unsafe-to-copy
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1070
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1071 You can use these definitions:
1072 PNG_HANDLE_CHUNK_AS_DEFAULT 0
1073 PNG_HANDLE_CHUNK_NEVER 1
1074 PNG_HANDLE_CHUNK_IF_SAFE 2
1075 PNG_HANDLE_CHUNK_ALWAYS 3
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1076
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1077 chunk_list - list of chunks affected (a byte string,
1078 five bytes per chunk, NULL or '\0' if
1079 num_chunks is 0)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1080
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1081 num_chunks - number of chunks affected; if 0, all
Glenn Randers-Pehrsondff799e2004-08-07 21:42:49 -0500[diff] [blame]1082 unknown chunks are affected. If nonzero,
1083 only the chunks in the list are affected
1084
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1085Unknown chunks declared in this way will be saved as raw data onto a
1086list of png_unknown_chunk structures. If a chunk that is normally
1087known to libpng is named in the list, it will be handled as unknown,
1088according to the "keep" directive. If a chunk is named in successive
1089instances of png_set_keep_unknown_chunks(), the final instance will
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]1090take precedence. The IHDR and IEND chunks should not be named in
1091chunk_list; if they are, libpng will process them normally anyway.
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1092If you know that your application will never make use of some particular
1093chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1094
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1095Here is an example of the usage of png_set_keep_unknown_chunks(),
1096where the private "vpAg" chunk will later be processed by a user chunk
1097callback function:
1098
1099 png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
1100
1101 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1102 png_byte unused_chunks[]=
1103 {
1104 104, 73, 83, 84, (png_byte) '\0', /* hIST */
1105 105, 84, 88, 116, (png_byte) '\0', /* iTXt */
1106 112, 67, 65, 76, (png_byte) '\0', /* pCAL */
1107 115, 67, 65, 76, (png_byte) '\0', /* sCAL */
1108 115, 80, 76, 84, (png_byte) '\0', /* sPLT */
1109 116, 73, 77, 69, (png_byte) '\0', /* tIME */
1110 };
1111 #endif
1112
1113 ...
1114
1115 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
1116 /* ignore all unknown chunks: */
1117 png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1118
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1119 /* except for vpAg: */
1120 png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1121
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1122 /* also ignore unused known chunks: */
1123 png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
1124 (int)sizeof(unused_chunks)/5);
1125 #endif
1126
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]1127.SS User limits
1128
1129The PNG specification allows the width and height of an image to be as
1130large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
1131Since very few applications really need to process such large images,
1132we have imposed an arbitrary 1-million limit on rows and columns.
1133Larger images will be rejected immediately with a png_error() call. If
Glenn Randers-Pehrson0cb906d2011-06-11 14:22:22 -0500[diff] [blame]1134you wish to change this limit, you can use
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]1135
1136 png_set_user_limits(png_ptr, width_max, height_max);
1137
1138to set your own limits, or use width_max = height_max = 0x7fffffffL
1139to allow all valid dimensions (libpng may reject some very large images
1140anyway because of potential buffer overflow conditions).
1141
1142You should put this statement after you create the PNG structure and
1143before calling png_read_info(), png_read_png(), or png_process_data().
Glenn Randers-Pehrsoncc277082011-06-10 21:17:34 -0500[diff] [blame]1144
1145When writing a PNG datastream, put this statement before calling
1146png_write_info() or png_write_png().
1147
Glenn Randers-Pehrson800d1e92008-08-20 17:25:21 -0500[diff] [blame]1148If you need to retrieve the limits that are being applied, use
1149
1150 width_max = png_get_user_width_max(png_ptr);
1151 height_max = png_get_user_height_max(png_ptr);
1152
1153The PNG specification sets no limit on the number of ancillary chunks
1154allowed in a PNG datastream. You can impose a limit on the total number
1155of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
1156
1157 png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
1158
1159where 0x7fffffffL means unlimited. You can retrieve this limit with
1160
1161 chunk_cache_max = png_get_chunk_cache_max(png_ptr);
1162
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]1163This limit also applies to the number of buffers that can be allocated
1164by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
1165
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]1166You can also set a limit on the amount of memory that a compressed chunk
1167other than IDAT can occupy, with
1168
1169 png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
1170
1171and you can retrieve the limit with
1172
1173 chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
1174
1175Any chunks that would cause either of these limits to be exceeded will
1176be ignored.
1177
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1178.SS Information about your system
1179
1180If you intend to display the PNG or to incorporate it in other image data you
1181need to tell libpng information about your display or drawing surface so that
1182libpng can convert the values in the image to match the display.
1183
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1184From libpng-1.5.4 this information can be set before reading the PNG file
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1185header. In earlier versions png_set_gamma() existed but behaved incorrectly if
1186called before the PNG file header had been read and png_set_alpha_mode() did not
1187exist.
1188
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1189If you need to support versions prior to libpng-1.5.4 test the version number
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1190as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
1191described in the appropriate manual page.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1192
1193You give libpng the encoding expected by your system expressed as a 'gamma'
1194value. You can also specify a default encoding for the PNG file in
1195case the required information is missing from the file. By default libpng
1196assumes that the PNG data matches your system, to keep this default call:
1197
1198 png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
1199
1200or you can use the fixed point equivalent:
1201
1202 png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_gamma);
1203
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1204If you don't know the gamma for your system it is probably 2.2 - a good
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1205approximation to the IEC standard for display systems (sRGB). If images are
1206too contrasty or washed out you got the value wrong - check your system
1207documentation!
1208
1209Many systems permit the system gamma to be changed via a lookup table in the
1210display driver, a few systems, including older Macs, change the response by
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1211default. As of 1.5.4 three special values are available to handle common
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1212situations:
1213
1214 PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
1215 standard. This matches almost all systems.
1216 PNG_GAMMA_MAC_18: Indicates that the system is an older (pre Mac OS 10.6)
1217 Apple Macintosh system with the default settings.
1218 PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates that the
1219 system expects data with no gamma encoding.
1220
1221You would use the linear (unencoded) value if you need to process the pixel
1222values further because this avoids the need to decode and reencode each
1223component value whenever arithmetic is performed. A lot of graphics software
1224uses linear values for this reason, often with higher precision component values
1225to preserve overall accuracy.
1226
1227The second thing you may need to tell libpng about is how your system handles
1228alpha channel information. Some, but not all, PNG files contain an alpha
1229channel. To display these files correctly you need to compose the data onto a
1230suitable background, as described in the PNG specification.
1231
1232Libpng only supports composing onto a single color (using png_set_background;
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1233see below). Otherwise you must do the composition yourself and, in this case,
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1234you may need to call png_set_alpha_mode:
1235
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1236#if PNG_LIBPNG_VER >= 10504
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1237 png_set_alpha_mode(png_ptr, mode, screen_gamma);
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1238#else
1239 png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1240#endif
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1241
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1242The screen_gamma value is the same as the argument to png_set_gamma; however,
1243how it affects the output depends on the mode. png_set_alpha_mode() sets the
1244file gamma default to 1/screen_gamma, so normally you don't need to call
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1245png_set_gamma. If you need different defaults call png_set_gamma() before
1246png_set_alpha_mode() - if you call it after it will override the settings made
1247by png_set_alpha_mode().
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1248
1249The mode is as follows:
1250
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1251 PNG_ALPHA_PNG: The data is encoded according to the PNG specification. Red,
1252green and blue, or gray, components are gamma encoded color
1253values and are not premultiplied by the alpha value. The
1254alpha value is a linear measure of the contribution of the
1255pixel to the corresponding final output pixel.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1256
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1257You should normally use this format if you intend to perform
1258color correction on the color values; most, maybe all, color
1259correction software has no handling for the alpha channel and,
1260anyway, the math to handle pre-multiplied component values is
1261unnecessarily complex.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1262
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1263Before you do any arithmetic on the component values you need
1264to remove the gamma encoding and multiply out the alpha
1265channel. See the PNG specification for more detail. It is
1266important to note that when an image with an alpha channel is
1267scaled, linear encoded, pre-multiplied component values must
1268be used!
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1269
1270The remaining modes assume you don't need to do any further color correction or
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1271that if you do, your color correction software knows all about alpha (it
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1272probably doesn't!)
1273
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1274 PNG_ALPHA_STANDARD: The data libpng produces
1275is encoded in the standard way
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1276assumed by most correctly written graphics software.
1277The gamma encoding will be removed by libpng and the
1278linear component values will be pre-multiplied by the
1279alpha channel.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1280
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1281With this format the final image must be re-encoded to
1282match the display gamma before the image is displayed.
1283If your system doesn't do that, yet still seems to
1284perform arithmetic on the pixels without decoding them,
1285it is broken - check out the modes below.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1286
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1287With PNG_ALPHA_STANDARD libpng always produces linear
1288component values, whatever screen_gamma you supply. The
1289screen_gamma value is, however, used as a default for
1290the file gamma if the PNG file has no gamma information.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1291
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1292If you call png_set_gamma() after png_set_alpha_mode() you
1293will override the linear encoding. Instead the
1294pre-multiplied pixel values will be gamma encoded but
1295the alpha channel will still be linear. This may
1296actually match the requirements of some broken software,
1297but it is unlikely.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1298
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1299While linear 8-bit data is often used it has
1300insufficient precision for any image with a reasonable
1301dynamic range. To avoid problems, and if your software
1302supports it, use png_set_expand_16() to force all
1303components to 16 bits.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1304
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1305 PNG_ALPHA_OPTIMIZED: This mode is the same
1306as PNG_ALPHA_STANDARD except that
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1307completely opaque pixels are gamma encoded according to
1308the screen_gamma value. Pixels with alpha less than 1.0
1309will still have linear components.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1310
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1311Use this format if you have control over your
1312compositing software and do don't do other arithmetic
1313(such as scaling) on the data you get from libpng. Your
1314compositing software can simply copy opaque pixels to
1315the output but still has linear values for the
1316non-opaque pixels.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1317
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1318In normal compositing, where the alpha channel encodes
1319partial pixel coverage (as opposed to broad area
1320translucency), the inaccuracies of the 8-bit
1321representation of non-opaque pixels are irrelevant.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1322
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1323You can also try this format if your software is broken;
1324it might look better.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1325
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1326 PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD;
1327however, all component values,
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1328including the alpha channel are gamma encoded. This is
1329an appropriate format to try if your software, or more
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1330likely hardware, is totally broken, i.e., if it performs
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1331linear arithmetic directly on gamma encoded values.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1332
1333In most cases of broken software or hardware the bug in the final display
1334manifests as a subtle halo around composited parts of the image. You may not
1335even perceive this as a halo; the composited part of the image may simply appear
1336separate from the background, as though it had been cut out of paper and pasted
1337on afterward.
1338
1339If you don't have to deal with bugs in software or hardware, or if you can fix
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1340them, there are three recommended ways of using png_set_alpha_mode():
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1341
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1342 png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
1343 screen_gamma);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1344
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1345You can do color correction on the result (libpng does not currently
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1346support color correction internally). When you handle the alpha channel
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1347you need to undo the gamma encoding and multiply out the alpha.
1348
1349 png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
1350 screen_gamma);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1351 png_set_expand_16(png_ptr);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1352
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1353If you are using the high level interface, don't call png_set_expand_16();
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1354instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1355
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1356With this mode you can't do color correction, but you can do arithmetic,
1357including composition and scaling, on the data without further processing.
1358
1359 png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
1360 screen_gamma);
1361
1362You can avoid the expansion to 16-bit components with this mode, but you
1363lose the ability to scale the image or perform other linear arithmetic.
1364All you can do is compose the result onto a matching output. Since this
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1365mode is libpng-specific you also need to write your own composition
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1366software.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1367
1368If you don't need, or can't handle, the alpha channel you can call
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1369png_set_background() to remove it by compositing against a fixed color. Don't
1370call png_set_strip_alpha() to do this - it will leave spurious pixel values in
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1371transparent parts of this image.
1372
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]1373 png_set_background(png_ptr, &background_color,
1374 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1375
1376The background_color is an RGB or grayscale value according to the data format
1377libpng will produce for you. Because you don't yet know the format of the PNG
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]1378file, if you call png_set_background at this point you must arrange for the
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1379format produced by libpng to always have 8-bit or 16-bit components and then
1380store the color as an 8-bit or 16-bit color as appropriate. The color contains
1381separate gray and RGB component values, so you can let libpng produce gray or
1382RGB output according to the input format, but low bit depth grayscale images
Glenn Randers-Pehrsonab389792011-07-09 19:35:22 -0500[diff] [blame]1383must always be converted to at least 8-bit format. (Even though low bit depth
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1384grayscale images can't have an alpha channel they can have a transparent
1385color!)
1386
1387You set the transforms you need later, either as flags to the high level
1388interface or libpng API calls for the low level interface. For reference the
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1389settings and API calls required are:
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1390
13918-bit values:
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]1392 PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
1393 png_set_expand(png_ptr); png_set_scale_16(png_ptr);
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1394
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1395 If you must get exactly the same inaccurate results
1396 produced by default in versions prior to libpng-1.5.4,
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]1397 use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr)
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1398 instead.
1399
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]140016-bit values:
1401 PNG_TRANSFORM_EXPAND_16
1402 png_set_expand_16(png_ptr);
1403
1404In either case palette image data will be expanded to RGB. If you just want
1405color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
1406to the list.
1407
1408Calling png_set_background before the PNG file header is read will not work
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1409prior to libpng-1.5.4. Because the failure may result in unexpected warnings or
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1410errors it is therefore much safer to call png_set_background after the head has
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]1411been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1412used with the high level interface.
1413
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1414.SS The high-level read interface
1415
1416At this point there are two ways to proceed; through the high-level
1417read interface, or through a sequence of low-level read operations.
1418You can use the high-level interface if (a) you are willing to read
1419the entire image into memory, and (b) the input transformations
1420you want to do are limited to the following set:
1421
1422 PNG_TRANSFORM_IDENTITY No transformation
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]1423 PNG_TRANSFORM_SCALE_16 Strip 16-bit samples to
1424 8-bit accurately
1425 PNG_TRANSFORM_STRIP_16 Chop 16-bit samples to
1426 8-bit less accurately
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1427 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1428 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
1429 samples to bytes
1430 PNG_TRANSFORM_PACKSWAP Change order of packed
1431 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1432 PNG_TRANSFORM_EXPAND Perform set_expand()
1433 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1434 PNG_TRANSFORM_SHIFT Normalize pixels to the
1435 sBIT depth
1436 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
1437 to BGRA
1438 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
1439 to AG
1440 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
1441 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1442 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
Glenn Randers-Pehrson99708d52009-06-29 17:30:00 -0500[diff] [blame]1443 PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
1444 to RGB (or GA to RGBA)
John Bowlera9b34192011-05-08 19:46:51 -0500[diff] [blame]1445 PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1446
1447(This excludes setting a background color, doing gamma transformation,
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]1448quantizing, and setting filler.) If this is the case, simply do this:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1449
1450 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1451
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]1452where png_transforms is an integer containing the bitwise OR of some
1453set of transformation flags. This call is equivalent to png_read_info(),
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1454followed the set of transformations indicated by the transform mask,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1455then png_read_image(), and finally png_read_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1456
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1457(The final parameter of this call is not yet used. Someday it might point
1458to transformation parameters required by some future input transform.)
1459
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]1460You must use png_transforms and not call any png_set_transform() functions
1461when you use png_read_png().
1462
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1463After you have called png_read_png(), you can retrieve the image data
1464with
1465
1466 row_pointers = png_get_rows(png_ptr, info_ptr);
1467
1468where row_pointers is an array of pointers to the pixel data for each row:
1469
1470 png_bytep row_pointers[height];
1471
1472If you know your image size and pixel size ahead of time, you can allocate
1473row_pointers prior to calling png_read_png() with
1474
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1475 if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]1476 png_error (png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1477 "Image is too tall to process in memory");
1478
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]1479 if (width > PNG_UINT_32_MAX/pixel_size)
1480 png_error (png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1481 "Image is too wide to process in memory");
1482
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1483 row_pointers = png_malloc(png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1484 height*png_sizeof(png_bytep));
1485
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]1486 for (int i=0; i<height, i++)
1487 row_pointers[i]=NULL; /* security precaution */
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1488
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1489 for (int i=0; i<height, i++)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1490 row_pointers[i]=png_malloc(png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1491 width*pixel_size);
1492
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]1493 png_set_rows(png_ptr, info_ptr, &row_pointers);
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1494
1495Alternatively you could allocate your image in one big block and define
1496row_pointers[i] to point into the proper places in your block.
1497
1498If you use png_set_rows(), the application is responsible for freeing
1499row_pointers (and row_pointers[i], if they were separately allocated).
1500
1501If you don't allocate row_pointers ahead of time, png_read_png() will
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1502do it, and it'll be free'ed by libpng when you call png_destroy_*().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1503
1504.SS The low-level read interface
1505
1506If you are going the low-level route, you are now ready to read all
1507the file information up to the actual image data. You do this with a
1508call to png_read_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1509
1510 png_read_info(png_ptr, info_ptr);
1511
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1512This will process all chunks up to but not including the image data.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1513
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1514This also copies some of the data from the PNG file into the decode structure
1515for use in later transformations. Important information copied in is:
1516
15171) The PNG file gamma from the gAMA chunk. This overwrites the default value
1518provided by an earlier call to png_set_gamma or png_set_alpha_mode.
1519
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]15202) Prior to libpng-1.5.4 the background color from a bKGd chunk. This
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1521damages the information provided by an earlier call to png_set_background
Glenn Randers-Pehrsonab389792011-07-09 19:35:22 -0500[diff] [blame]1522resulting in unexpected behavior. Libpng-1.5.4 no longer does this.
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1523
15243) The number of significant bits in each component value. Libpng uses this to
1525optimize gamma handling by reducing the internal lookup table sizes.
1526
15274) The transparent color information from a tRNS chunk. This can be modified by
1528a later call to png_set_tRNS.
1529
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1530.SS Querying the info structure
1531
1532Functions are used to get the information from the info_ptr once it
1533has been read. Note that these fields may not be completely filled
1534in until png_read_end() has read the chunk data following the image.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1535
1536 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1537 &bit_depth, &color_type, &interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1538 &compression_type, &filter_method);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1539
1540 width - holds the width of the image
1541 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1542
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1543 height - holds the height of the image
1544 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1545
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1546 bit_depth - holds the bit depth of one of the
1547 image channels. (valid values are
1548 1, 2, 4, 8, 16 and depend also on
1549 the color_type. See also
1550 significant bits (sBIT) below).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1551
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1552 color_type - describes which color/alpha channels
1553 are present.
1554 PNG_COLOR_TYPE_GRAY
1555 (bit depths 1, 2, 4, 8, 16)
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1556 PNG_COLOR_TYPE_GRAY_ALPHA
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1557 (bit depths 8, 16)
1558 PNG_COLOR_TYPE_PALETTE
1559 (bit depths 1, 2, 4, 8)
1560 PNG_COLOR_TYPE_RGB
1561 (bit_depths 8, 16)
1562 PNG_COLOR_TYPE_RGB_ALPHA
1563 (bit_depths 8, 16)
1564
1565 PNG_COLOR_MASK_PALETTE
1566 PNG_COLOR_MASK_COLOR
1567 PNG_COLOR_MASK_ALPHA
1568
Glenn Randers-Pehrson2cb633b2011-01-21 08:31:29 -0600[diff] [blame]1569 interlace_type - (PNG_INTERLACE_NONE or
1570 PNG_INTERLACE_ADAM7)
1571
1572 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1573 for PNG 1.0)
1574
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]1575 filter_method - (must be PNG_FILTER_TYPE_BASE
1576 for PNG 1.0, and can also be
1577 PNG_INTRAPIXEL_DIFFERENCING if
1578 the PNG datastream is embedded in
1579 a MNG-1.0 datastream)
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1580
1581 Any or all of interlace_type, compression_type, or
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1582 filter_method can be NULL if you are
1583 not interested in their values.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1584
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1585 Note that png_get_IHDR() returns 32-bit data into
1586 the application's width and height variables.
1587 This is an unsafe situation if these are 16-bit
1588 variables. In such situations, the
1589 png_get_image_width() and png_get_image_height()
1590 functions described below are safer.
1591
1592 width = png_get_image_width(png_ptr,
1593 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1594
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1595 height = png_get_image_height(png_ptr,
1596 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1597
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1598 bit_depth = png_get_bit_depth(png_ptr,
1599 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1600
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1601 color_type = png_get_color_type(png_ptr,
1602 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1603
Glenn Randers-Pehrson2cb633b2011-01-21 08:31:29 -0600[diff] [blame]1604 interlace_type = png_get_interlace_type(png_ptr,
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1605 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1606
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1607 compression_type = png_get_compression_type(png_ptr,
1608 info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1609
Glenn Randers-Pehrson2cb633b2011-01-21 08:31:29 -0600[diff] [blame]1610 filter_method = png_get_filter_type(png_ptr,
Glenn Randers-Pehrson0bfb58f2009-09-30 23:07:22 -0500[diff] [blame]1611 info_ptr);
1612
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1613 channels = png_get_channels(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1614
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1615 channels - number of channels of info for the
1616 color type (valid values are 1 (GRAY,
1617 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1618 4 (RGB_ALPHA or RGB + filler byte))
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1619
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1620 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1621
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1622 rowbytes - number of bytes needed to hold a row
1623
1624 signature = png_get_signature(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1625
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1626 signature - holds the signature read from the
1627 file (if any). The data is kept in
1628 the same offset it would be if the
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1629 whole signature were read (i.e. if an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1630 application had already read in 4
1631 bytes of signature before starting
1632 libpng, the remaining 4 bytes would
1633 be in signature[4] through signature[7]
1634 (see png_set_sig_bytes())).
1635
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1636These are also important, but their validity depends on whether the chunk
1637has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1638png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1639data has been read, or zero if it is missing. The parameters to the
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]1640png_get_<chunk> are set directly if they are simple data types, or a
1641pointer into the info_ptr is returned for any complex types.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1642
1643 png_get_PLTE(png_ptr, info_ptr, &palette,
1644 &num_palette);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1645
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1646 palette - the palette for the file
1647 (array of png_color)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1648
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1649 num_palette - number of entries in the palette
1650
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]1651 png_get_gAMA(png_ptr, info_ptr, &file_gamma);
Glenn Randers-Pehrson27742382011-01-27 09:37:34 -0600[diff] [blame]1652 png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1653
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]1654 file_gamma - the gamma at which the file is
1655 written (PNG_INFO_gAMA)
1656
1657 int_file_gamma - 100,000 times the gamma at which the
1658 file is written
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1659
John Bowlerbbd17bd2011-08-25 17:48:18 -0500[diff] [blame]1660 png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x, &red_y,
1661 &green_x, &green_y, &blue_x, &blue_y)
1662 png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, &green_X,
1663 &green_Y, &green_Z, &blue_X, &blue_Y, &blue_Z)
1664 png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, &int_white_y,
1665 &int_red_x, &int_red_y, &int_green_x, &int_green_y,
1666 &int_blue_x, &int_blue_y)
1667 png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
1668 &int_red_Z, &int_green_X, &int_green_Y, &int_green_Z,
1669 &int_blue_X, &int_blue_Y, &int_blue_Z)
1670
1671 {white,red,green,blue}_{x,y}
1672 A color space encoding specified using the chromaticities
1673 of the end points and the white point. (PNG_INFO_cHRM)
1674
1675 {red,green,blue}_{X,Y,Z}
1676 A color space encoding specified using the encoding end
1677 points - the CIE tristimulus specification of the intended
1678 color of the red, green and blue channels in the PNG RGB
1679 data. The white point is simply the sum of the three end
1680 points. (PNG_INFO_cHRM)
1681
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1682 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1683
Glenn Randers-Pehrson27742382011-01-27 09:37:34 -0600[diff] [blame]1684 file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1685 The presence of the sRGB chunk
1686 means that the pixel data is in the
1687 sRGB color space. This chunk also
1688 implies specific values of gAMA and
1689 cHRM.
1690
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1691 png_get_iCCP(png_ptr, info_ptr, &name,
1692 &compression_type, &profile, &proflen);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1693
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]1694 name - The profile name.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1695
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]1696 compression_type - The compression type; always
1697 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1698 You may give NULL to this argument to
1699 ignore it.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1700
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]1701 profile - International Color Consortium color
1702 profile data. May contain NULs.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1703
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]1704 proflen - length of profile data in bytes.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1705
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1706 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1707
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1708 sig_bit - the number of significant bits for
1709 (PNG_INFO_sBIT) each of the gray,
1710 red, green, and blue channels,
1711 whichever are appropriate for the
1712 given color type (png_color_16)
1713
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]1714 png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
1715 &num_trans, &trans_color);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1716
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]1717 trans_alpha - array of alpha (transparency)
1718 entries for palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1719
Glenn Randers-Pehrsonf3c51e42011-01-15 10:25:25 -0600[diff] [blame]1720 num_trans - number of transparent entries
1721 (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1722
Glenn Randers-Pehrson56f63962008-10-06 10:16:17 -0500[diff] [blame]1723 trans_color - graylevel or color sample values of
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]1724 the single transparent color for
1725 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1726
1727 png_get_hIST(png_ptr, info_ptr, &hist);
1728 (PNG_INFO_hIST)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1729
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1730 hist - histogram of palette (array of
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1731 png_uint_16)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1732
1733 png_get_tIME(png_ptr, info_ptr, &mod_time);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1734
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1735 mod_time - time image was last modified
1736 (PNG_VALID_tIME)
1737
1738 png_get_bKGD(png_ptr, info_ptr, &background);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1739
Glenn Randers-Pehrsonab389792011-07-09 19:35:22 -0500[diff] [blame]1740 background - background color (of type
1741 png_color_16p) (PNG_VALID_bKGD)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1742 valid 16-bit red, green and blue
1743 values, regardless of color_type
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1744
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1745 num_comments = png_get_text(png_ptr, info_ptr,
1746 &text_ptr, &num_text);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1747
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1748 num_comments - number of comments
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1749
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1750 text_ptr - array of png_text holding image
1751 comments
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1752
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1753 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1754 on "text" PNG_TEXT_COMPRESSION_NONE
1755 PNG_TEXT_COMPRESSION_zTXt
1756 PNG_ITXT_COMPRESSION_NONE
1757 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1758
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1759 text_ptr[i].key - keyword for comment. Must contain
1760 1-79 characters.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1761
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1762 text_ptr[i].text - text comments for current
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1763 keyword. Can be empty.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1764
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1765 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1766 after decompression, 0 for iTXt
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1767
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1768 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1769 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1770
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1771 text_ptr[i].lang - language of comment (empty
1772 string for unknown).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1773
Glenn Randers-Pehrson73d57cb2002-03-25 18:49:08 -0600[diff] [blame]1774 text_ptr[i].lang_key - keyword in UTF-8
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1775 (empty string for unknown).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1776
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]1777 Note that the itxt_length, lang, and lang_key
Glenn Randers-Pehrson680da022011-11-21 17:05:41 -0600[diff] [blame]1778 members of the text_ptr structure only exist when the
1779 library is built with iTXt chunk support. Prior to
1780 libpng-1.4.0 the library was built by default without
1781 iTXt support. Also note that when iTXt is supported,
1782 they contain NULL pointers when the "compression"
1783 field contains PNG_TEXT_COMPRESSION_NONE or
1784 PNG_TEXT_COMPRESSION_zTXt.
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]1785
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1786 num_text - number of comments (same as
1787 num_comments; you can put NULL here
1788 to avoid the duplication)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1789
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1790 Note while png_set_text() will accept text, language,
1791 and translated keywords that can be NULL pointers, the
1792 structure returned by png_get_text will always contain
1793 regular zero-terminated C strings. They might be
1794 empty strings but they will never be NULL pointers.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1795
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1796 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1797 &palette_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1798
1799 num_spalettes - number of sPLT chunks read.
1800
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1801 palette_ptr - array of palette structures holding
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1802 contents of one or more sPLT chunks
1803 read.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1804
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1805 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1806 &unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1807
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1808 offset_x - positive offset from the left edge
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1809 of the screen (can be negative)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1810
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1811 offset_y - positive offset from the top edge
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1812 of the screen (can be negative)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1813
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1814 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1815
1816 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1817 &unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1818
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1819 res_x - pixels/unit physical resolution in
1820 x direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1821
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1822 res_y - pixels/unit physical resolution in
1823 x direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1824
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1825 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1826 PNG_RESOLUTION_METER
1827
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1828 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1829 &height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1830
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1831 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1832
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1833 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1834
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1835 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1836 (width and height are doubles)
1837
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1838 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1839 &height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1840
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1841 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1842
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1843 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1844 (expressed as a string)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1845
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1846 height - height of a pixel in physical scale units
1847 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1848
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1849 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1850 info_ptr, &unknowns)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1851
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1852 unknowns - array of png_unknown_chunk
1853 structures holding unknown chunks
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1854
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1855 unknowns[i].name - name of unknown chunk
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1856
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1857 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1858
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1859 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1860
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1861 unknowns[i].location - position of chunk in file
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1862
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1863 The value of "i" corresponds to the order in which the
1864 chunks were read from the PNG file or inserted with the
1865 png_set_unknown_chunks() function.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1866
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]1867 The value of "location" is a bitwise "or" of
1868
1869 PNG_HAVE_IHDR (0x01)
1870 PNG_HAVE_PLTE (0x02)
1871 PNG_AFTER_IDAT (0x08)
1872
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1873The data from the pHYs chunk can be retrieved in several convenient
1874forms:
1875
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1876 res_x = png_get_x_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1877 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1878
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1879 res_y = png_get_y_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1880 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1881
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1882 res_x_and_y = png_get_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1883 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1884
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1885 res_x = png_get_x_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1886 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1887
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1888 res_y = png_get_y_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1889 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1890
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1891 res_x_and_y = png_get_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1892 info_ptr)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1893
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1894 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1895 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1896
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1897 Each of these returns 0 [signifying "unknown"] if
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1898 the data is not present or if res_x is 0;
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1899 res_x_and_y is 0 if res_x != res_y
1900
1901 Note that because of the way the resolutions are
1902 stored internally, the inch conversions won't
1903 come out to exactly even number. For example,
1904 72 dpi is stored as 0.28346 pixels/meter, and
1905 when this is retrieved it is 71.9988 dpi, so
1906 be sure to round the returned value appropriately
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]1907 if you want to display a reasonable-looking result.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1908
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1909The data from the oFFs chunk can be retrieved in several convenient
1910forms:
1911
1912 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1913
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1914 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1915
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1916 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1917
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1918 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1919
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1920 Each of these returns 0 [signifying "unknown" if both
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1921 x and y are 0] if the data is not present or if the
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]1922 chunk is present but the unit is the pixel. The
1923 remark about inexact inch conversions applies here
1924 as well, because a value in inches can't always be
1925 converted to microns and back without some loss
1926 of precision.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1927
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1928For more information, see the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1929PNG specification for chunk contents. Be careful with trusting
1930rowbytes, as some of the transformations could increase the space
1931needed to hold a row (expand, filler, gray_to_rgb, etc.).
1932See png_read_update_info(), below.
1933
1934A quick word about text_ptr and num_text. PNG stores comments in
1935keyword/text pairs, one pair per chunk, with no limit on the number
1936of text chunks, and a 2^31 byte limit on their size. While there are
1937suggested keywords, there is no requirement to restrict the use to these
1938strings. It is strongly suggested that keywords and text be sensible
1939to humans (that's the point), so don't use abbreviations. Non-printing
1940symbols are not allowed. See the PNG specification for more details.
1941There is also no requirement to have text after the keyword.
1942
1943Keywords should be limited to 79 Latin-1 characters without leading or
1944trailing spaces, but non-consecutive spaces are allowed within the
1945keyword. It is possible to have the same keyword any number of times.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1946The text_ptr is an array of png_text structures, each holding a
1947pointer to a language string, a pointer to a keyword and a pointer to
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1948a text string. The text string, language code, and translated
1949keyword may be empty or NULL pointers. The keyword/text
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1950pairs are put into the array in the order that they are received.
1951However, some or all of the text chunks may be after the image, so, to
1952make sure you have read all the text chunks, don't mess with these
1953until after you read the stuff after the image. This will be
1954mentioned again below in the discussion that goes with png_read_end().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1955
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1956.SS Input transformations
1957
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1958After you've read the header information, you can set up the library
1959to handle any special transformations of the image data. The various
1960ways to transform the data will be described in the order that they
1961should occur. This is important, as some of these change the color
1962type and/or bit depth of the data, and some others only work on
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1963certain color types and bit depths.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1964
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]1965Transformations you request are ignored if they don't have any meaning for a
1966particular input data format. However some transformations can have an effect
1967as a result of a previous transformation. If you specify a contradictory set of
1968transformations, for example both adding and removing the alpha channel, you
1969cannot predict the final result.
1970
1971The color used for the transparency values should be supplied in the same
1972format/depth as the current image data. It is stored in the same format/depth
1973as the image data in a tRNS chunk, so this is what libpng expects for this data.
1974
1975The color used for the background value depends on the need_expand argument as
1976described below.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1977
1978Data will be decoded into the supplied row buffers packed into bytes
1979unless the library has been told to transform it into another format.
1980For example, 4 bit/pixel paletted or grayscale data will be returned
19812 pixels/byte with the leftmost pixel in the high-order bits of the
1982byte, unless png_set_packing() is called. 8-bit RGB data will be stored
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1983in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
1984is called to insert filler bytes, either before or after each RGB triplet.
198516-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]1986byte of the color value first, unless png_set_scale_16() is called to
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]1987transform it to regular RGB RGB triplets, or png_set_filler() or
1988png_set_add alpha() is called to insert filler bytes, either before or
1989after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]1990be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(),
1991or png_set_scale_16().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1992
1993The following code transforms grayscale images of less than 8 to 8 bits,
1994changes paletted images to RGB, and adds a full alpha channel if there is
1995transparency information in a tRNS chunk. This is most useful on
1996grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1997viewing application that wishes to treat all images in the same way.
1998
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1999 if (color_type == PNG_COLOR_TYPE_PALETTE)
2000 png_set_palette_to_rgb(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2001
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2002 if (png_get_valid(png_ptr, info_ptr,
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2003 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
2004
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2005 if (color_type == PNG_COLOR_TYPE_GRAY &&
2006 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
2007
2008The first two functions are actually aliases for png_set_expand(), added
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2009in libpng version 1.0.4, with the function names expanded to improve code
2010readability. In some future version they may actually do different
2011things.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2012
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]2013As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
2014added. It expands the sample depth without changing tRNS to alpha.
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]2015
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2016As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2017png_set_expand(); however, the resultant channels have 16 bits rather than 8.
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2018Use this when the output color or gray channels are made linear to avoid fairly
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2019severe accuracy loss.
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]2020
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2021 if (bit_depth < 16)
2022 png_set_expand_16(png_ptr);
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]2023
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2024PNG can have files with 16 bits per channel. If you only can handle
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]20258 bits per channel, this will strip the pixels down to 8-bit.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2026
2027 if (bit_depth == 16)
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2028#if PNG_LIBPNG_VER >= 10504
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]2029 png_set_scale_16(png_ptr);
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2030#else
2031 png_set_strip_16(png_ptr);
2032#endif
2033
2034(The more accurate "png_set_scale_16()" API became available in libpng version
20351.5.4).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2036
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2037If you need to process the alpha channel on the image separately from the image
2038data (for example if you convert it to a bitmap mask) it is possible to have
2039libpng strip the channel leaving just RGB or gray data:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2040
2041 if (color_type & PNG_COLOR_MASK_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2042 png_set_strip_alpha(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2043
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2044If you strip the alpha channel you need to find some other way of dealing with
2045the information. If, instead, you want to convert the image to an opaque
2046version with no alpha channel use png_set_background; see below.
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2047
2048As of libpng version 1.5.2, almost all useful expansions are supported, the
Glenn Randers-Pehrsoncd116fa2011-05-17 06:56:50 -0500[diff] [blame]2049major ommissions are conversion of grayscale to indexed images (which can be
2050done trivially in the application) and conversion of indexed to grayscale (which
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2051can be done by a trivial manipulation of the palette.)
2052
2053In the following table, the 01 means grayscale with depth<8, 31 means
2054indexed with depth<8, other numerals represent the color type, "T" means
2055the tRNS chunk is present, A means an alpha channel is present, and O
2056means tRNS or alpha is present but all pixels in the image are opaque.
2057
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]2058 FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2059 TO
2060 01 - [G] - - - - - - - - - - - - -
2061 31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q
2062 0 1 G + . . G G G G G G B B GB GB
2063 0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt
2064 0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt
2065 2 C P C C C + . . C - - CB CB B B
2066 2T Ct - Ct C C t + t - - - CBt CBt Bt Bt
2067 2O Ct - Ct C C t t + - - - CBt CBt Bt Bt
2068 3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q
2069 3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt
2070 3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt
2071 4A lA G A T T GA GT GT GA GT GT + BA G GBA
2072 4O lA GBA A T T GA GT GT GA GT GT BA + GBA G
2073 6A CA PA CA C C A T tT PA P P C CBA + BA
2074 6O CA PBA CA C C A tT T PA P P CBA C BA +
2075
2076Within the matrix,
2077 "+" identifies entries where 'from' and 'to' are the same.
2078 "-" means the transformation is not supported.
2079 "." means nothing is necessary (a tRNS chunk can just be ignored).
2080 "t" means the transformation is obtained by png_set_tRNS.
2081 "A" means the transformation is obtained by png_set_add_alpha().
2082 "X" means the transformation is obtained by png_set_expand().
2083 "1" means the transformation is obtained by
2084 png_set_expand_gray_1_2_4_to_8() (and by png_set_expand() if there
2085 is no transparency in the original or the final format).
2086 "C" means the transformation is obtained by png_set_gray_to_rgb().
Glenn Randers-Pehrsonc36074e2011-05-16 09:08:51 -0500[diff] [blame]2087 "G" means the transformation is obtained by png_set_rgb_to_gray().
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2088 "P" means the transformation is obtained by
2089 png_set_expand_palette_to_rgb().
2090 "p" means the transformation is obtained by png_set_packing().
2091 "Q" means the transformation is obtained by png_set_quantize().
2092 "T" means the transformation is obtained by png_set_tRNS_to_alpha().
2093 "B" means the transformation is obtained by png_set_background(), or
2094 png_strip_alpha().
John Bowler63d059a2011-02-12 09:03:44 -0600[diff] [blame]2095
2096When an entry has multiple transforms listed all are required to cause the
2097right overall transformation. When two transforms are separated by a comma
2098either will do the job. When transforms are enclosed in [] the transform should
2099do the job but this is currently unimplemented - a different format will result
2100if the suggested transformations are used.
2101
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2102In PNG files, the alpha channel in an image
2103is the level of opacity. If you need the alpha channel in an image to
2104be the level of transparency instead of opacity, you can invert the
2105alpha channel (or the tRNS chunk data) after it's read, so that 0 is
2106fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
2107images) is fully transparent, with
2108
2109 png_set_invert_alpha(png_ptr);
2110
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2111PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2112they can, resulting in, for example, 8 pixels per byte for 1 bit
2113files. This code expands to 1 pixel per byte without changing the
2114values of the pixels:
2115
2116 if (bit_depth < 8)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2117 png_set_packing(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2118
2119PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
2120stored in a PNG image have been "scaled" or "shifted" up to the next
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]2121higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
2122to 8 bits/sample in the range [0, 255]). However, it is also possible
2123to convert the PNG pixel data back to the original bit depth of the
2124image. This call reduces the pixels back down to the original bit depth:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2125
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]2126 png_color_8p sig_bit;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2127
2128 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2129 png_set_shift(png_ptr, sig_bit);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2130
2131PNG files store 3-color pixels in red, green, blue order. This code
2132changes the storage of the pixels to blue, green, red:
2133
2134 if (color_type == PNG_COLOR_TYPE_RGB ||
2135 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2136 png_set_bgr(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2137
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]2138PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
2139into 4 or 8 bytes for windowing systems that need them in this format:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2140
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]2141 if (color_type == PNG_COLOR_TYPE_RGB)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2142 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2143
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2144where "filler" is the 8 or 16-bit number to fill with, and the location is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2145either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
2146you want the filler before the RGB or after. This transformation
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]2147does not affect images that already have full alpha channels. To add an
2148opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
2149will generate RGBA pixels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2150
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2151Note that png_set_filler() does not change the color type. If you want
2152to do that, you can add a true alpha channel with
2153
2154 if (color_type == PNG_COLOR_TYPE_RGB ||
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2155 color_type == PNG_COLOR_TYPE_GRAY)
2156 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2157
2158where "filler" contains the alpha value to assign to each pixel.
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]2159This function was added in libpng-1.2.7.
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]2160
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2161If you are reading an image with an alpha channel, and you need the
2162data as ARGB instead of the normal PNG format RGBA:
2163
2164 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2165 png_set_swap_alpha(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2166
2167For some uses, you may want a grayscale image to be represented as
2168RGB. This code will do that conversion:
2169
2170 if (color_type == PNG_COLOR_TYPE_GRAY ||
2171 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2172 png_set_gray_to_rgb(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2173
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2174Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2175with alpha.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2176
2177 if (color_type == PNG_COLOR_TYPE_RGB ||
2178 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2179 png_set_rgb_to_gray(png_ptr, error_action, double red_weight,
2180 double green_weight);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2181
2182 error_action = 1: silently do the conversion
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2183
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2184 error_action = 2: issue a warning if the original
2185 image has any pixel where
2186 red != green or red != blue
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2187
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2188 error_action = 3: issue an error and abort the
2189 conversion if the original
2190 image has any pixel where
2191 red != green or red != blue
2192
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2193 red_weight: weight of red component
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2194
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2195 green_weight: weight of green component
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2196 If either weight is negative, default
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2197 weights are used.
2198
2199In the corresponding fixed point API the red_weight and green_weight values are
2200simply scaled by 100,000:
2201
2202 png_set_rgb_to_gray(png_ptr, error_action, png_fixed_point red_weight,
2203 png_fixed_point green_weight);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2204
2205If you have set error_action = 1 or 2, you can
2206later check whether the image really was gray, after processing
2207the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
2208It will return a png_byte that is zero if the image was gray or
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]22091 if there were any non-gray pixels. Background and sBIT data
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2210will be silently converted to grayscale, using the green channel
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2211data for sBIT, regardless of the error_action setting.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2212
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2213The default values come from the PNG file cHRM chunk if present; otherwise, the
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2214defaults correspond to the ITU-R recommendation 709, and also the sRGB color
2215space, as recommended in the Charles Poynton's Colour FAQ,
2216<http://www.poynton.com/>, in section 9:
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2217
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2218 <http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2219
Glenn Randers-Pehrson6c988972011-07-29 12:31:16 -0500[diff] [blame]2220 Y = 0.2126 * R + 0.7152 * G + 0.0722 * B
2221
2222Previous versions of this document, 1998 through 2002, recommended a slightly
2223different formula:
2224
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2225 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
2226
Glenn Randers-Pehrson6c988972011-07-29 12:31:16 -0500[diff] [blame]2227Libpng uses an integer approximation:
2228
2229 Y = (6968 * R + 23434 * G + 2366 * B)/32768
2230
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2231The calculation is done in a linear colorspace, if the image gamma
Glenn Randers-Pehrson9962b842011-01-24 00:12:14 -0600[diff] [blame]2232can be determined.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2233
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2234The png_set_background() function has been described already; it tells libpng to
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2235composite images with alpha or simple transparency against the supplied
2236background color. For compatibility with versions of libpng earlier than
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]2237libpng-1.5.4 it is recommended that you call the function after reading the file
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2238header, even if you don't want to use the color in a bKGD chunk, if one exists.
2239
2240If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
2241you may use this color, or supply another color more suitable for
2242the current display (e.g., the background color from a web page). You
2243need to tell libpng how the color is represented, both the format of the
Glenn Randers-Pehrsonab389792011-07-09 19:35:22 -0500[diff] [blame]2244component values in the color (the number of bits) and the gamma encoding of the
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2245color. The function takes two arguments, background_gamma_mode and need_expand
Glenn Randers-Pehrsonab389792011-07-09 19:35:22 -0500[diff] [blame]2246to convey this information, however only two combinations are likely to be
2247useful:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2248
Glenn Randers-Pehrsoncb47e202011-07-10 06:55:14 -0500[diff] [blame]2249 png_color_16 my_background;
2250 png_color_16p image_background;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2251
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]2252 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2253 png_set_background(png_ptr, image_background,
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2254 PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2255 else
Glenn Randers-Pehrsoncb47e202011-07-10 06:55:14 -0500[diff] [blame]2256 png_set_background(png_ptr, &my_background,
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2257 PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2258
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2259The second call was described above - my_background is in the format of the
2260final, display, output produced by libpng. Because you now know the format of
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]2261the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
2262output and to retain palette images (the palette colors will be modified
2263appropriately and the tRNS chunk removed.) However, if you are doing this,
2264take great care not to ask for transformations without checking first that
2265they apply!
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2266
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2267In the first call the background color has the original bit depth and color type
2268of the PNG file. So, for palette images the color is supplied as a palette
2269index and for low bit greyscale images the color is a reduced bit value in
2270image_background->gray.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2271
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2272If you didn't call png_set_gamma() before reading the file header, for example
2273if you need your code to remain compatible with older versions of libpng prior
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]2274to libpng-1.5.4, this is the place to call it.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2275
John Bowlercb0b2962011-05-12 21:48:29 -0500[diff] [blame]2276Do not call it if you called png_set_alpha_mode(); doing so will damage the
2277settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
2278supported then you can certainly do png_set_gamma() before reading the PNG
2279header.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2280
Glenn Randers-Pehrsonc7822512011-05-07 21:23:43 -0500[diff] [blame]2281This API unconditionally sets the screen and file gamma values, so it will
2282override the value in the PNG file unless it is called before the PNG file
2283reading starts. For this reason you must always call it with the PNG file
2284value when you call it in this position:
2285
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]2286 if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
2287 png_set_gamma(png_ptr, screen_gamma, file_gamma);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2288
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2289 else
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2290 png_set_gamma(png_ptr, screen_gamma, 0.45455);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2291
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2292If you need to reduce an RGB file to a paletted file, or if a paletted
2293file has more entries then will fit on your screen, png_set_quantize()
Glenn Randers-Pehrson862cb202010-04-16 22:12:51 -0500[diff] [blame]2294will do that. Note that this is a simple match quantization that merely
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2295finds the closest color available. This should work fairly well with
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2296optimized palettes, but fairly badly with linear color cubes. If you
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2297pass a palette that is larger than maximum_colors, the file will
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2298reduce the number of colors in the palette so it will fit into
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2299maximum_colors. If there is a histogram, libpng will use it to make
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2300more intelligent choices when reducing the palette. If there is no
2301histogram, it may not do as good a job.
2302
2303 if (color_type & PNG_COLOR_MASK_COLOR)
2304 {
2305 if (png_get_valid(png_ptr, info_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2306 PNG_INFO_PLTE))
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2307 {
2308 png_uint_16p histogram = NULL;
2309
2310 png_get_hIST(png_ptr, info_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2311 &histogram);
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2312 png_set_quantize(png_ptr, palette, num_palette,
2313 max_screen_colors, histogram, 1);
2314 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2315
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]2316 else
2317 {
2318 png_color std_color_cube[MAX_SCREEN_COLORS] =
2319 { ... colors ... };
2320
2321 png_set_quantize(png_ptr, std_color_cube,
2322 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
2323 NULL,0);
2324 }
2325 }
2326
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2327PNG files describe monochrome as black being zero and white being one.
2328The following code will reverse this (make black be one and white be
2329zero):
2330
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]2331 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
2332 png_set_invert_mono(png_ptr);
2333
2334This function can also be used to invert grayscale and gray-alpha images:
2335
2336 if (color_type == PNG_COLOR_TYPE_GRAY ||
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2337 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2338 png_set_invert_mono(png_ptr);
2339
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]2340PNG files store 16-bit pixels in network byte order (big-endian,
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2341ie. most significant bits first). This code changes the storage to the
2342other way (little-endian, i.e. least significant bits first, the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2343way PCs store them):
2344
2345 if (bit_depth == 16)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2346 png_set_swap(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2347
2348If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2349need to change the order the pixels are packed into bytes, you can use:
2350
2351 if (bit_depth < 8)
2352 png_set_packswap(png_ptr);
2353
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2354Finally, you can write your own transformation function if none of
2355the existing ones meets your needs. This is done by setting a callback
2356with
2357
2358 png_set_read_user_transform_fn(png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2359 read_transform_fn);
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2360
2361You must supply the function
2362
Glenn Randers-Pehrson93215672011-02-13 19:42:19 -0600[diff] [blame]2363 void read_transform_fn(png_structp png_ptr, png_row_infop
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2364 row_info, png_bytep data)
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2365
2366See pngtest.c for a working example. Your function will be called
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]2367after all of the other transformations have been processed. Take care with
2368interlaced images if you do the interlace yourself - the width of the row is the
2369width in 'row_info', not the overall image width.
2370
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]2371If supported, libpng provides two information routines that you can use to find
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]2372where you are in processing the image:
2373
2374 png_get_current_pass_number(png_structp png_ptr);
2375 png_get_current_row_number(png_structp png_ptr);
2376
2377Don't try using these outside a transform callback - firstly they are only
2378supported if user transforms are supported, secondly they may well return
2379unexpected results unless the row is actually being processed at the moment they
2380are called.
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2381
John Bowlercd113452011-02-16 06:15:13 -0600[diff] [blame]2382With interlaced
2383images the value returned is the row in the input sub-image image. Use
2384PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
2385find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
2386
2387The discussion of interlace handling above contains more information on how to
2388use these values.
2389
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2390You can also set up a pointer to a user structure for use by your
2391callback function, and you can inform libpng that your transform
2392function will change the number of channels or bit depth with the
2393function
2394
2395 png_set_user_transform_info(png_ptr, user_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2396 user_depth, user_channels);
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2397
2398The user's application, not libpng, is responsible for allocating and
2399freeing any memory required for the user structure.
2400
2401You can retrieve the pointer via the function
2402png_get_user_transform_ptr(). For example:
2403
2404 voidp read_user_transform_ptr =
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2405 png_get_user_transform_ptr(png_ptr);
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2406
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2407The last thing to handle is interlacing; this is covered in detail below,
2408but you must call the function here if you want libpng to handle expansion
2409of the interlaced image.
2410
2411 number_of_passes = png_set_interlace_handling(png_ptr);
2412
2413After setting the transformations, libpng can update your png_info
2414structure to reflect any transformations you've requested with this
Glenn Randers-Pehrson968c2312011-09-26 16:35:22 -0500[diff] [blame]2415call.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2416
2417 png_read_update_info(png_ptr, info_ptr);
2418
Glenn Randers-Pehrson968c2312011-09-26 16:35:22 -0500[diff] [blame]2419This is most useful to update the info structure's rowbytes
2420field so you can use it to allocate your image memory. This function
2421will also update your palette with the correct screen_gamma and
2422background if these have been given with the calls above. You may
2423only call png_read_update_info() once with a particular info_ptr.
2424
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2425After you call png_read_update_info(), you can allocate any
2426memory you need to hold the image. The row data is simply
2427raw byte data for all forms of images. As the actual allocation
2428varies among applications, no example will be given. If you
2429are allocating one large chunk, you will need to build an
2430array of pointers to each row, as it will be needed for some
2431of the functions below.
2432
Glenn Randers-Pehrson968c2312011-09-26 16:35:22 -0500[diff] [blame]2433Remember: Before you call png_read_update_info(), the png_get_*()
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]2434functions return the values corresponding to the original PNG image.
2435After you call png_read_update_info the values refer to the image
2436that libpng will output. Consequently you must call all the png_set_
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2437functions before you call png_read_update_info(). This is particularly
2438important for png_set_interlace_handling() - if you are going to call
2439png_read_update_info() you must call png_set_interlace_handling() before
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]2440it unless you want to receive interlaced output.
2441
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2442.SS Reading image data
2443
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2444After you've allocated memory, you can read the image data.
2445The simplest way to do this is in one function call. If you are
2446allocating enough memory to hold the whole image, you can just
2447call png_read_image() and libpng will read in all the image data
2448and put it in the memory area supplied. You will need to pass in
2449an array of pointers to each row.
2450
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]2451This function automatically handles interlacing, so you don't
2452need to call png_set_interlace_handling() (unless you call
2453png_read_update_info()) or call this function multiple times, or any
2454of that other stuff necessary with png_read_rows().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2455
2456 png_read_image(png_ptr, row_pointers);
2457
2458where row_pointers is:
2459
2460 png_bytep row_pointers[height];
2461
2462You can point to void or char or whatever you use for pixels.
2463
2464If you don't want to read in the whole image at once, you can
2465use png_read_rows() instead. If there is no interlacing (check
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2466interlace_type == PNG_INTERLACE_NONE), this is simple:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2467
2468 png_read_rows(png_ptr, row_pointers, NULL,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2469 number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2470
2471where row_pointers is the same as in the png_read_image() call.
2472
2473If you are doing this just one row at a time, you can do this with
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2474a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2475
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2476 png_bytep row_pointer = row;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2477 png_read_row(png_ptr, row_pointer, NULL);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2478
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2479If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
2480get somewhat harder. The only current (PNG Specification version 1.2)
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2481interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
2482a somewhat complicated 2D interlace scheme, known as Adam7, that
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2483breaks down an image into seven smaller images of varying size, based
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2484on an 8x8 grid. This number is defined (from libpng 1.5) as
2485PNG_INTERLACE_ADAM7_PASSES in png.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2486
2487libpng can fill out those images or it can give them to you "as is".
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2488It is almost always better to have libpng handle the interlacing for you.
2489If you want the images filled out, there are two ways to do that. The one
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2490mentioned in the PNG specification is to expand each pixel to cover
2491those pixels that have not been read yet (the "rectangle" method).
2492This results in a blocky image for the first pass, which gradually
2493smooths out as more pixels are read. The other method is the "sparkle"
2494method, where pixels are drawn only in their final locations, with the
2495rest of the image remaining whatever colors they were initialized to
2496before the start of the read. The first method usually looks better,
2497but tends to be slower, as there are more pixels to put in the rows.
2498
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2499If, as is likely, you want libpng to expand the images, call this before
2500calling png_start_read_image() or png_read_update_info():
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2501
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2502 if (interlace_type == PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2503 number_of_passes
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2504 = png_set_interlace_handling(png_ptr);
2505
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2506This will return the number of passes needed. Currently, this is seven,
2507but may change if another interlace type is added. This function can be
2508called even if the file is not interlaced, where it will return one pass.
2509You then need to read the whole image 'number_of_passes' times. Each time
2510will distribute the pixels from the current pass to the correct place in
2511the output image, so you need to supply the same rows to png_read_rows in
2512each pass.
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]2513
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2514If you are not going to display the image after each pass, but are
2515going to wait until the entire image is read in, use the sparkle
2516effect. This effect is faster and the end result of either method
2517is exactly the same. If you are planning on displaying the image
2518after each pass, the "rectangle" effect is generally considered the
2519better looking one.
2520
2521If you only want the "sparkle" effect, just call png_read_rows() as
2522normal, with the third parameter NULL. Make sure you make pass over
2523the image number_of_passes times, and you don't change the data in the
2524rows between calls. You can change the locations of the data, just
2525not the data. Each pass only writes the pixels appropriate for that
2526pass, and assumes the data from previous passes is still valid.
2527
2528 png_read_rows(png_ptr, row_pointers, NULL,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2529 number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2530
2531If you only want the first effect (the rectangles), do the same as
2532before except pass the row buffer in the third parameter, and leave
2533the second parameter NULL.
2534
2535 png_read_rows(png_ptr, NULL, row_pointers,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2536 number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2537
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2538If you don't want libpng to handle the interlacing details, just call
2539png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
2540Each of the images is a valid image by itself, however you will almost
2541certainly need to distribute the pixels from each sub-image to the
2542correct place. This is where everything gets very tricky.
2543
2544If you want to retrieve the separate images you must pass the correct
2545number of rows to each successive call of png_read_rows(). The calculation
2546gets pretty complicated for small images, where some sub-images may
2547not even exist because either their width or height ends up zero.
2548libpng provides two macros to help you in 1.5 and later versions:
2549
2550 png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
2551 png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
2552
2553Respectively these tell you the width and height of the sub-image
2554corresponding to the numbered pass. 'pass' is in in the range 0 to 6 -
2555this can be confusing because the specification refers to the same passes
2556as 1 to 7! Be careful, you must check both the width and height before
2557calling png_read_rows() and not call it for that pass if either is zero.
2558
2559You can, of course, read each sub-image row by row. If you want to
2560produce optimal code to make a pixel-by-pixel transformation of an
2561interlaced image this is the best approach; read each row of each pass,
2562transform it, and write it out to a new interlaced image.
2563
2564If you want to de-interlace the image yourself libpng provides further
2565macros to help that tell you where to place the pixels in the output image.
2566Because the interlacing scheme is rectangular - sub-image pixels are always
2567arranged on a rectangular grid - all you need to know for each pass is the
2568starting column and row in the output image of the first pixel plus the
2569spacing between each pixel. As of libpng 1.5 there are four macros to
2570retrieve this information:
2571
2572 png_uint_32 x = PNG_PASS_START_COL(pass);
2573 png_uint_32 y = PNG_PASS_START_ROW(pass);
2574 png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass);
2575 png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass);
2576
2577These allow you to write the obvious loop:
2578
2579 png_uint_32 input_y = 0;
2580 png_uint_32 output_y = PNG_PASS_START_ROW(pass);
2581
2582 while (output_y < output_image_height)
2583 {
2584 png_uint_32 input_x = 0;
2585 png_uint_32 output_x = PNG_PASS_START_COL(pass);
2586
2587 while (output_x < output_image_width)
2588 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2589 image[output_y][output_x] =
2590 subimage[pass][input_y][input_x++];
2591
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2592 output_x += xStep;
2593 }
2594
2595 ++input_y;
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2596 output_y += yStep;
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2597 }
2598
2599Notice that the steps between successive output rows and columns are
2600returned as shifts. This is possible because the pixels in the subimages
2601are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original
2602image. In practice you may need to directly calculate the output coordinate
2603given an input coordinate. libpng provides two further macros for this
2604purpose:
2605
2606 png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass);
2607 png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass);
2608
2609Finally a pair of macros are provided to tell you if a particular image
2610row or column appears in a given pass:
2611
2612 int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass);
2613 int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass);
2614
2615Bear in mind that you will probably also need to check the width and height
2616of the pass in addition to the above to be sure the pass even exists!
2617
2618With any luck you are convinced by now that you don't want to do your own
2619interlace handling. In reality normally the only good reason for doing this
2620is if you are processing PNG files on a pixel-by-pixel basis and don't want
2621to load the whole file into memory when it is interlaced.
2622
2623libpng includes a test program, pngvalid, that illustrates reading and
2624writing of interlaced images. If you can't get interlacing to work in your
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]2625code and don't want to leave it to libpng (the recommended approach), see
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2626how pngvalid.c does it.
2627
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2628.SS Finishing a sequential read
2629
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]2630After you are finished reading the image through the
2631low-level interface, you can finish reading the file. If you are
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2632interested in comments or time, which may be stored either before or
2633after the image data, you should pass the separate png_info struct if
2634you want to keep the comments from before and after the image
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]2635separate.
2636
2637 png_infop end_info = png_create_info_struct(png_ptr);
2638
2639 if (!end_info)
2640 {
2641 png_destroy_read_struct(&png_ptr, &info_ptr,
2642 (png_infopp)NULL);
2643 return (ERROR);
2644 }
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2645
2646 png_read_end(png_ptr, end_info);
2647
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]2648If you are not interested, you should still call png_read_end()
2649but you can pass NULL, avoiding the need to create an end_info structure.
2650
2651 png_read_end(png_ptr, (png_infop)NULL);
2652
Glenn Randers-Pehrson99778e12011-04-20 17:43:52 -0500[diff] [blame]2653If you don't call png_read_end(), then your file pointer will be
2654left pointing to the first chunk after the last IDAT, which is probably
2655not what you want if you expect to read something beyond the end of
2656the PNG datastream.
2657
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2658When you are done, you can free all memory allocated by libpng like this:
2659
2660 png_destroy_read_struct(&png_ptr, &info_ptr,
2661 &end_info);
2662
Glenn Randers-Pehrson20786be2011-04-20 22:20:40 -0500[diff] [blame]2663or, if you didn't create an end_info structure,
2664
2665 png_destroy_read_struct(&png_ptr, &info_ptr,
2666 (png_infopp)NULL);
2667
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2668It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2669point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2670
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2671 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2672
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2673 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2674 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2675 more of
2676 PNG_FREE_PLTE, PNG_FREE_TRNS,
2677 PNG_FREE_HIST, PNG_FREE_ICCP,
2678 PNG_FREE_PCAL, PNG_FREE_ROWS,
2679 PNG_FREE_SCAL, PNG_FREE_SPLT,
2680 PNG_FREE_TEXT, PNG_FREE_UNKN,
2681 or simply PNG_FREE_ALL
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2682
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2683 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2684 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2685
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2686This function may be safely called when the relevant storage has
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]2687already been freed, or has not yet been allocated, or was allocated
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]2688by the user and not by libpng, and will in those cases do nothing.
2689The "seq" parameter is ignored if only one item of the selected data
2690type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
2691are allowed for the data type identified in the mask, such as text or
2692sPLT, only the n'th item in the structure is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2693
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2694The default behavior is only to free data that was allocated internally
2695by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2696or so that it will free data that was allocated by the user with png_malloc()
2697or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2698
2699 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2700
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2701 freer - one of
2702 PNG_DESTROY_WILL_FREE_DATA
2703 PNG_SET_WILL_FREE_DATA
2704 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2705
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2706 mask - which data elements are affected
2707 same choices as in png_free_data()
2708
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2709This function only affects data that has already been allocated.
2710You can call this function after reading the PNG data but before calling
2711any png_set_*() functions, to control whether the user or the png_set_*()
2712function is responsible for freeing any existing data that might be present,
2713and again after the png_set_*() functions to control whether the user
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2714or png_destroy_*() is supposed to free the data. When the user assumes
2715responsibility for libpng-allocated data, the application must use
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2716png_free() to free it, and when the user transfers responsibility to libpng
2717for data that the user has allocated, the user must have used png_malloc()
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]2718or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2719
2720If you allocated your row_pointers in a single block, as suggested above in
2721the description of the high level read interface, you must not transfer
2722responsibility for freeing it to the png_set_rows or png_read_destroy function,
2723because they would also try to free the individual row_pointers[i].
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2724
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2725If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2726separately, do not transfer responsibility for freeing text_ptr to libpng,
2727because when libpng fills a png_text structure it combines these members with
2728the key member, and png_free_data() will free only text_ptr.key. Similarly,
2729if you transfer responsibility for free'ing text_ptr from libpng to your
2730application, your application must not separately free those members.
2731
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2732The png_free_data() function will turn off the "valid" flag for anything
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]2733it frees. If you need to turn the flag off for a chunk that was freed by
2734your application instead of by libpng, you can use
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2735
2736 png_set_invalid(png_ptr, info_ptr, mask);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2737
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2738 mask - identifies the chunks to be made invalid,
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2739 containing the bitwise OR of one or
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]2740 more of
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2741 PNG_INFO_gAMA, PNG_INFO_sBIT,
2742 PNG_INFO_cHRM, PNG_INFO_PLTE,
2743 PNG_INFO_tRNS, PNG_INFO_bKGD,
2744 PNG_INFO_hIST, PNG_INFO_pHYs,
2745 PNG_INFO_oFFs, PNG_INFO_tIME,
2746 PNG_INFO_pCAL, PNG_INFO_sRGB,
2747 PNG_INFO_iCCP, PNG_INFO_sPLT,
2748 PNG_INFO_sCAL, PNG_INFO_IDAT
2749
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2750For a more compact example of reading a PNG image, see the file example.c.
2751
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2752.SS Reading PNG files progressively
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2753
2754The progressive reader is slightly different then the non-progressive
2755reader. Instead of calling png_read_info(), png_read_rows(), and
2756png_read_end(), you make one call to png_process_data(), which calls
2757callbacks when it has the info, a row, or the end of the image. You
2758set up these callbacks with png_set_progressive_read_fn(). You don't
2759have to worry about the input/output functions of libpng, as you are
2760giving the library the data directly in png_process_data(). I will
2761assume that you have read the section on reading PNG files above,
2762so I will only highlight the differences (although I will show
2763all of the code).
2764
2765png_structp png_ptr;
2766png_infop info_ptr;
2767
2768 /* An example code fragment of how you would
2769 initialize the progressive reader in your
2770 application. */
2771 int
2772 initialize_png_reader()
2773 {
2774 png_ptr = png_create_read_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]2775 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2776 user_error_fn, user_warning_fn);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2777
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2778 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2779 return (ERROR);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2780
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2781 info_ptr = png_create_info_struct(png_ptr);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2782
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2783 if (!info_ptr)
2784 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2785 png_destroy_read_struct(&png_ptr,
2786 (png_infopp)NULL, (png_infopp)NULL);
2787 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2788 }
2789
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2790 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2791 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2792 png_destroy_read_struct(&png_ptr, &info_ptr,
2793 (png_infopp)NULL);
2794 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2795 }
2796
2797 /* This one's new. You can provide functions
2798 to be called when the header info is valid,
2799 when each row is completed, and when the image
2800 is finished. If you aren't using all functions,
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2801 you can specify NULL parameters. Even when all
2802 three functions are NULL, you need to call
2803 png_set_progressive_read_fn(). You can use
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2804 any struct as the user_ptr (cast to a void pointer
2805 for the function call), and retrieve the pointer
2806 from inside the callbacks using the function
2807
2808 png_get_progressive_ptr(png_ptr);
2809
2810 which will return a void pointer, which you have
2811 to cast appropriately.
2812 */
2813 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2814 info_callback, row_callback, end_callback);
2815
2816 return 0;
2817 }
2818
2819 /* A code fragment that you call as you receive blocks
2820 of data */
2821 int
2822 process_data(png_bytep buffer, png_uint_32 length)
2823 {
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2824 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2825 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2826 png_destroy_read_struct(&png_ptr, &info_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2827 (png_infopp)NULL);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2828 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2829 }
2830
2831 /* This one's new also. Simply give it a chunk
2832 of data from the file stream (in order, of
2833 course). On machines with segmented memory
2834 models machines, don't give it any more than
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2835 64K. The library seems to run fine with sizes
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2836 of 4K. Although you can give it much less if
2837 necessary (I assume you can give it chunks of
2838 1 byte, I haven't tried less then 256 bytes
2839 yet). When this function returns, you may
2840 want to display any rows that were generated
2841 in the row callback if you don't already do
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2842 so there.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2843 */
2844 png_process_data(png_ptr, info_ptr, buffer, length);
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]2845
2846 /* At this point you can call png_process_data_skip if
2847 you want to handle data the library will skip yourself;
2848 it simply returns the number of bytes to skip (and stops
2849 libpng skipping that number of bytes on the next
2850 png_process_data call).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2851 return 0;
2852 }
2853
2854 /* This function is called (as set by
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2855 png_set_progressive_read_fn() above) when enough data
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2856 has been supplied so all of the header has been
2857 read.
2858 */
2859 void
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2860 info_callback(png_structp png_ptr, png_infop info)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2861 {
2862 /* Do any setup here, including setting any of
2863 the transformations mentioned in the Reading
2864 PNG files section. For now, you _must_ call
2865 either png_start_read_image() or
2866 png_read_update_info() after all the
2867 transformations are set (even if you don't set
2868 any). You may start getting rows before
2869 png_process_data() returns, so this is your
2870 last chance to prepare for that.
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2871
2872 This is where you turn on interlace handling,
2873 assuming you don't want to do it yourself.
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]2874
2875 If you need to you can stop the processing of
2876 your original input data at this point by calling
2877 png_process_data_pause. This returns the number
2878 of unprocessed bytes from the last png_process_data
2879 call - it is up to you to ensure that the next call
2880 sees these bytes again. If you don't want to bother
2881 with this you can get libpng to cache the unread
2882 bytes by setting the 'save' parameter (see png.h) but
2883 then libpng will have to copy the data internally.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2884 */
2885 }
2886
2887 /* This function is called when each row of image
2888 data is complete */
2889 void
2890 row_callback(png_structp png_ptr, png_bytep new_row,
Glenn Randers-Pehrsone68f5a32001-05-14 09:20:53 -0500[diff] [blame]2891 png_uint_32 row_num, int pass)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2892 {
2893 /* If the image is interlaced, and you turned
2894 on the interlace handler, this function will
2895 be called for every row in every pass. Some
2896 of these rows will not be changed from the
2897 previous pass. When the row is not changed,
2898 the new_row variable will be NULL. The rows
2899 and passes are called in order, so you don't
2900 really need the row_num and pass, but I'm
2901 supplying them because it may make your life
2902 easier.
2903
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2904 If you did not turn on interlace handling then
2905 the callback is called for each row of each
2906 sub-image when the image is interlaced. In this
2907 case 'row_num' is the row in the sub-image, not
2908 the row in the output image as it is in all other
2909 cases.
2910
2911 For the non-NULL rows of interlaced images when
2912 you have switched on libpng interlace handling,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2913 you must call png_progressive_combine_row()
2914 passing in the row and the old row. You can
2915 call this function for NULL rows (it will just
2916 return) and for non-interlaced images (it just
2917 does the memcpy for you) if it will make the
2918 code easier. Thus, you can just do this for
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]2919 all cases if you switch on interlace handling;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2920 */
2921
2922 png_progressive_combine_row(png_ptr, old_row,
2923 new_row);
2924
2925 /* where old_row is what was displayed for
Glenn Randers-Pehrson345bc271998-06-14 14:43:31 -0500[diff] [blame]2926 previously for the row. Note that the first
2927 pass (pass == 0, really) will completely cover
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2928 the old row, so the rows do not have to be
2929 initialized. After the first pass (and only
2930 for interlaced images), you will have to pass
2931 the current row, and the function will combine
2932 the old row and the new row.
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]2933
2934 You can also call png_process_data_pause in this
2935 callback - see above.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2936 */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2937 }
2938
2939 void
2940 end_callback(png_structp png_ptr, png_infop info)
2941 {
2942 /* This function is called after the whole image
2943 has been read, including any chunks after the
2944 image (up to and including the IEND). You
2945 will usually have the same info chunk as you
2946 had in the header, although some data may have
2947 been added to the comments and time fields.
2948
2949 Most people won't do much here, perhaps setting
2950 a flag that marks the image as finished.
2951 */
2952 }
2953
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2954
2955
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2956.SH IV. Writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2957
2958Much of this is very similar to reading. However, everything of
2959importance is repeated here, so you won't have to constantly look
2960back up in the reading section to understand writing.
2961
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2962.SS Setup
2963
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2964You will want to do the I/O initialization before you get into libpng,
2965so if it doesn't work, you don't have anything to undo. If you are not
2966using the standard I/O functions, you will need to replace them with
2967custom writing functions. See the discussion under Customizing libpng.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2968
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2969 FILE *fp = fopen(file_name, "wb");
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2970
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2971 if (!fp)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2972 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2973
2974Next, png_struct and png_info need to be allocated and initialized.
2975As these can be both relatively large, you may not want to store these
2976on the stack, unless you have stack space to spare. Of course, you
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2977will want to check if they return NULL. If you are also reading,
2978you won't want to name your read structure and your write structure
2979both "png_ptr"; you can call them anything you like, such as
2980"read_ptr" and "write_ptr". Look at pngtest.c, for example.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2981
2982 png_structp png_ptr = png_create_write_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]2983 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2984 user_error_fn, user_warning_fn);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2985
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2986 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2987 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2988
2989 png_infop info_ptr = png_create_info_struct(png_ptr);
2990 if (!info_ptr)
2991 {
2992 png_destroy_write_struct(&png_ptr,
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]2993 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]2994 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2995 }
2996
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]2997If you want to use your own memory allocation routines,
2998define PNG_USER_MEM_SUPPORTED and use
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2999png_create_write_struct_2() instead of png_create_write_struct():
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]3000
3001 png_structp png_ptr = png_create_write_struct_2
3002 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
3003 user_error_fn, user_warning_fn, (png_voidp)
3004 user_mem_ptr, user_malloc_fn, user_free_fn);
3005
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3006After you have these structures, you will need to set up the
3007error handling. When libpng encounters an error, it expects to
3008longjmp() back to your routine. Therefore, you will need to call
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3009setjmp() and pass the png_jmpbuf(png_ptr). If you
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3010write the file from different routines, you will need to update
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3011the png_jmpbuf(png_ptr) every time you enter a new routine that will
3012call a png_*() function. See your documentation of setjmp/longjmp
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3013for your compiler for more information on setjmp/longjmp. See
3014the discussion on libpng error handling in the Customizing Libpng
3015section below for more information on the libpng error handling.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3016
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3017 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3018 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3019 png_destroy_write_struct(&png_ptr, &info_ptr);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]3020 fclose(fp);
3021 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3022 }
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3023 ...
3024 return;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3025
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3026If you would rather avoid the complexity of setjmp/longjmp issues,
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]3027you can compile libpng with PNG_NO_SETJMP, in which case
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3028errors will result in a call to PNG_ABORT() which defaults to abort().
3029
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]3030You can #define PNG_ABORT() to a function that does something
3031more useful than abort(), as long as your function does not
3032return.
3033
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3034Now you need to set up the output code. The default for libpng is to
3035use the C function fwrite(). If you use this, you will need to pass a
3036valid FILE * in the function png_init_io(). Be sure that the file is
3037opened in binary mode. Again, if you wish to handle writing data in
3038another way, see the discussion on libpng I/O handling in the Customizing
3039Libpng section below.
3040
3041 png_init_io(png_ptr, fp);
3042
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]3043If you are embedding your PNG into a datastream such as MNG, and don't
3044want libpng to write the 8-byte signature, or if you have already
3045written the signature in your application, use
3046
3047 png_set_sig_bytes(png_ptr, 8);
3048
3049to inform libpng that it should not write a signature.
3050
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3051.SS Write callbacks
3052
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3053At this point, you can set up a callback function that will be
3054called after each row has been written, which you can use to control
3055a progress meter or the like. It's demonstrated in pngtest.c.
3056You must supply a function
3057
Glenn Randers-Pehrson81ce8892011-01-24 08:04:37 -0600[diff] [blame]3058 void write_row_callback(png_structp png_ptr, png_uint_32 row,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3059 int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3060 {
3061 /* put your code here */
3062 }
3063
3064(You can give it another name that you like instead of "write_row_callback")
3065
3066To inform libpng about your function, use
3067
3068 png_set_write_status_fn(png_ptr, write_row_callback);
3069
John Bowler59010e52011-02-16 06:16:31 -0600[diff] [blame]3070When this function is called the row has already been completely processed and
3071it has also been written out. The 'row' and 'pass' refer to the next row to be
3072handled. For the
3073non-interlaced case the row that was just handled is simply one less than the
3074passed in row number, and pass will always be 0. For the interlaced case the
3075same applies unless the row value is 0, in which case the row just handled was
3076the last one from one of the preceding passes. Because interlacing may skip a
3077pass you cannot be sure that the preceding pass is just 'pass-1', if you really
3078need to know what the last pass is record (row,pass) from the callback and use
3079the last recorded value each time.
3080
3081As with the user transform you can find the output row using the
3082PNG_ROW_FROM_PASS_ROW macro.
3083
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3084You now have the option of modifying how the compression library will
3085run. The following functions are mainly for testing, but may be useful
3086in some cases, like if you need to write PNG files extremely fast and
3087are willing to give up some compression, or if you want to get the
3088maximum possible compression at the expense of slower writing. If you
3089have no special needs in this area, let the library do what it wants by
3090not calling this function at all, as it has been tuned to deliver a good
3091speed/compression ratio. The second parameter to png_set_filter() is
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3092the filter method, for which the only valid values are 0 (as of the
3093July 1999 PNG specification, version 1.2) or 64 (if you are writing
3094a PNG datastream that is to be embedded in a MNG datastream). The third
3095parameter is a flag that indicates which filter type(s) are to be tested
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3096for each scanline. See the PNG specification for details on the specific
3097filter types.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3098
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3099
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3100 /* turn on or off filtering, and/or choose
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3101 specific filters. You can use either a single
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3102 PNG_FILTER_VALUE_NAME or the bitwise OR of one
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3103 or more PNG_FILTER_NAME masks.
3104 */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3105 png_set_filter(png_ptr, 0,
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3106 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
3107 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
3108 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]3109 PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3110 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
3111 PNG_ALL_FILTERS);
3112
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3113If an application wants to start and stop using particular filters during
3114compression, it should start out with all of the filters (to ensure that
3115the previous row of pixels will be stored in case it's needed later),
3116and then add and remove them after the start of compression.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3117
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3118If you are writing a PNG datastream that is to be embedded in a MNG
3119datastream, the second parameter can be either 0 or 64.
3120
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3121The png_set_compression_*() functions interface to the zlib compression
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3122library, and should mostly be ignored unless you really know what you are
3123doing. The only generally useful call is png_set_compression_level()
3124which changes how much time zlib spends on trying to compress the image
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3125data. See the Compression Library (zlib.h and algorithm.txt, distributed
3126with zlib) for details on the compression levels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3127
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]3128 #include zlib.h
3129
Glenn Randers-Pehrsona45f47c2011-04-01 15:31:26 -0500[diff] [blame]3130 /* Set the zlib compression level */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3131 png_set_compression_level(png_ptr,
3132 Z_BEST_COMPRESSION);
3133
Glenn Randers-Pehrsona45f47c2011-04-01 15:31:26 -0500[diff] [blame]3134 /* Set other zlib parameters for compressing IDAT */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3135 png_set_compression_mem_level(png_ptr, 8);
3136 png_set_compression_strategy(png_ptr,
3137 Z_DEFAULT_STRATEGY);
3138 png_set_compression_window_bits(png_ptr, 15);
3139 png_set_compression_method(png_ptr, 8);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3140 png_set_compression_buffer_size(png_ptr, 8192)
3141
Glenn Randers-Pehrsona45f47c2011-04-01 15:31:26 -0500[diff] [blame]3142 /* Set zlib parameters for text compression
3143 * If you don't call these, the parameters
3144 * fall back on those defined for IDAT chunks
3145 */
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]3146 png_set_text_compression_mem_level(png_ptr, 8);
3147 png_set_text_compression_strategy(png_ptr,
3148 Z_DEFAULT_STRATEGY);
3149 png_set_text_compression_window_bits(png_ptr, 15);
3150 png_set_text_compression_method(png_ptr, 8);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3151
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3152.SS Setting the contents of info for output
3153
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3154You now need to fill in the png_info structure with all the data you
3155wish to write before the actual image. Note that the only thing you
3156are allowed to write after the image is the text chunks and the time
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3157chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3158the latest PNG specification for more information on that. If you
3159wish to write them before the image, fill them in now, and flag that
3160data as being valid. If you want to wait until after the data, don't
3161fill them until png_write_end(). For all the fields in png_info and
3162their data types, see png.h. For explanations of what the fields
3163contain, see the PNG specification.
3164
3165Some of the more important parts of the png_info are:
3166
3167 png_set_IHDR(png_ptr, info_ptr, width, height,
3168 bit_depth, color_type, interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3169 compression_type, filter_method)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3170
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3171 width - holds the width of the image
3172 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3173
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3174 height - holds the height of the image
3175 in pixels (up to 2^31).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3176
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3177 bit_depth - holds the bit depth of one of the
3178 image channels.
3179 (valid values are 1, 2, 4, 8, 16
3180 and depend also on the
3181 color_type. See also significant
3182 bits (sBIT) below).
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3183
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3184 color_type - describes which color/alpha
3185 channels are present.
3186 PNG_COLOR_TYPE_GRAY
3187 (bit depths 1, 2, 4, 8, 16)
3188 PNG_COLOR_TYPE_GRAY_ALPHA
3189 (bit depths 8, 16)
3190 PNG_COLOR_TYPE_PALETTE
3191 (bit depths 1, 2, 4, 8)
3192 PNG_COLOR_TYPE_RGB
3193 (bit_depths 8, 16)
3194 PNG_COLOR_TYPE_RGB_ALPHA
3195 (bit_depths 8, 16)
3196
3197 PNG_COLOR_MASK_PALETTE
3198 PNG_COLOR_MASK_COLOR
3199 PNG_COLOR_MASK_ALPHA
3200
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3201 interlace_type - PNG_INTERLACE_NONE or
3202 PNG_INTERLACE_ADAM7
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3203
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3204 compression_type - (must be
3205 PNG_COMPRESSION_TYPE_DEFAULT)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3206
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3207 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
3208 or, if you are writing a PNG to
3209 be embedded in a MNG datastream,
3210 can also be
3211 PNG_INTRAPIXEL_DIFFERENCING)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3212
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3213If you call png_set_IHDR(), the call must appear before any of the
Glenn Randers-Pehrsond60c8862009-06-15 21:56:14 -0500[diff] [blame]3214other png_set_*() functions, because they might require access to some of
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3215the IHDR settings. The remaining png_set_*() functions can be called
3216in any order.
3217
Glenn Randers-Pehrsonb5444a12009-06-08 08:36:19 -0500[diff] [blame]3218If you wish, you can reset the compression_type, interlace_type, or
3219filter_method later by calling png_set_IHDR() again; if you do this, the
3220width, height, bit_depth, and color_type must be the same in each call.
Glenn Randers-Pehrson424c9852009-06-02 13:45:15 -0500[diff] [blame]3221
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3222 png_set_PLTE(png_ptr, info_ptr, palette,
3223 num_palette);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3224
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3225 palette - the palette for the file
3226 (array of png_color)
3227 num_palette - number of entries in the palette
3228
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]3229 png_set_gAMA(png_ptr, info_ptr, file_gamma);
3230 png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3231
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]3232 file_gamma - the gamma at which the image was
3233 created (PNG_INFO_gAMA)
3234
3235 int_file_gamma - 100,000 times the gamma at which
3236 the image was created
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3237
John Bowlerbbd17bd2011-08-25 17:48:18 -0500[diff] [blame]3238 png_set_cHRM(png_ptr, info_ptr, white_x, white_y, red_x, red_y,
3239 green_x, green_y, blue_x, blue_y)
3240 png_set_cHRM_XYZ(png_ptr, info_ptr, red_X, red_Y, red_Z, green_X,
3241 green_Y, green_Z, blue_X, blue_Y, blue_Z)
3242 png_set_cHRM_fixed(png_ptr, info_ptr, int_white_x, int_white_y,
3243 int_red_x, int_red_y, int_green_x, int_green_y,
3244 int_blue_x, int_blue_y)
3245 png_set_cHRM_XYZ_fixed(png_ptr, info_ptr, int_red_X, int_red_Y,
3246 int_red_Z, int_green_X, int_green_Y, int_green_Z,
3247 int_blue_X, int_blue_Y, int_blue_Z)
3248
3249 {white,red,green,blue}_{x,y}
3250 A color space encoding specified using the chromaticities
3251 of the end points and the white point.
3252
3253 {red,green,blue}_{X,Y,Z}
3254 A color space encoding specified using the encoding end
3255 points - the CIE tristimulus specification of the intended
3256 color of the red, green and blue channels in the PNG RGB
3257 data. The white point is simply the sum of the three end
3258 points.
3259
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3260 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3261
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3262 srgb_intent - the rendering intent
3263 (PNG_INFO_sRGB) The presence of
3264 the sRGB chunk means that the pixel
3265 data is in the sRGB color space.
3266 This chunk also implies specific
3267 values of gAMA and cHRM. Rendering
3268 intent is the CSS-1 property that
3269 has been defined by the International
3270 Color Consortium
3271 (http://www.color.org).
3272 It can be one of
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]3273 PNG_sRGB_INTENT_SATURATION,
3274 PNG_sRGB_INTENT_PERCEPTUAL,
3275 PNG_sRGB_INTENT_ABSOLUTE, or
3276 PNG_sRGB_INTENT_RELATIVE.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3277
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3278
3279 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
3280 srgb_intent);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3281
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3282 srgb_intent - the rendering intent
3283 (PNG_INFO_sRGB) The presence of the
3284 sRGB chunk means that the pixel
3285 data is in the sRGB color space.
3286 This function also causes gAMA and
3287 cHRM chunks with the specific values
3288 that are consistent with sRGB to be
3289 written.
3290
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3291 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3292 profile, proflen);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3293
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3294 name - The profile name.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3295
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3296 compression_type - The compression type; always
3297 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
3298 You may give NULL to this argument to
3299 ignore it.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3300
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3301 profile - International Color Consortium color
3302 profile data. May contain NULs.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3303
Glenn Randers-Pehrson4a5a1ec2011-01-15 11:43:28 -0600[diff] [blame]3304 proflen - length of profile data in bytes.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3305
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3306 png_set_sBIT(png_ptr, info_ptr, sig_bit);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3307
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3308 sig_bit - the number of significant bits for
3309 (PNG_INFO_sBIT) each of the gray, red,
3310 green, and blue channels, whichever are
3311 appropriate for the given color type
3312 (png_color_16)
3313
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]3314 png_set_tRNS(png_ptr, info_ptr, trans_alpha,
3315 num_trans, trans_color);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3316
Glenn Randers-Pehrson866b62a2009-08-08 16:33:14 -0500[diff] [blame]3317 trans_alpha - array of alpha (transparency)
3318 entries for palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3319
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]3320 num_trans - number of transparent entries
3321 (PNG_INFO_tRNS)
3322
Glenn Randers-Pehrsonb5444a12009-06-08 08:36:19 -0500[diff] [blame]3323 trans_color - graylevel or color sample values
3324 (in order red, green, blue) of the
3325 single transparent color for
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3326 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3327
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3328 png_set_hIST(png_ptr, info_ptr, hist);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3329
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3330 hist - histogram of palette (array of
Glenn Randers-Pehrson8d0bc0f2011-01-25 22:15:58 -0600[diff] [blame]3331 png_uint_16) (PNG_INFO_hIST)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3332
3333 png_set_tIME(png_ptr, info_ptr, mod_time);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3334
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3335 mod_time - time image was last modified
3336 (PNG_VALID_tIME)
3337
3338 png_set_bKGD(png_ptr, info_ptr, background);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3339
Glenn Randers-Pehrsonab389792011-07-09 19:35:22 -0500[diff] [blame]3340 background - background color (of type
3341 png_color_16p) (PNG_VALID_bKGD)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3342
3343 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3344
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3345 text_ptr - array of png_text holding image
3346 comments
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3347
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3348 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3349 on "text" PNG_TEXT_COMPRESSION_NONE
3350 PNG_TEXT_COMPRESSION_zTXt
3351 PNG_ITXT_COMPRESSION_NONE
3352 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3353 text_ptr[i].key - keyword for comment. Must contain
3354 1-79 characters.
3355 text_ptr[i].text - text comments for current
3356 keyword. Can be NULL or empty.
3357 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3358 after decompression, 0 for iTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3359 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3360 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3361 text_ptr[i].lang - language of comment (NULL or
3362 empty for unknown).
3363 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
3364 or empty for unknown).
Glenn Randers-Pehrson680da022011-11-21 17:05:41 -0600[diff] [blame]3365
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]3366 Note that the itxt_length, lang, and lang_key
Glenn Randers-Pehrson680da022011-11-21 17:05:41 -0600[diff] [blame]3367 members of the text_ptr structure only exist when the
3368 library is built with iTXt chunk support. Prior to
3369 libpng-1.4.0 the library was built by default without
3370 iTXt support. Also note that when iTXt is supported,
3371 they contain NULL pointers when the "compression"
3372 field contains PNG_TEXT_COMPRESSION_NONE or
3373 PNG_TEXT_COMPRESSION_zTXt.
Glenn Randers-Pehrson8f5846f2009-10-31 21:31:08 -0500[diff] [blame]3374
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3375 num_text - number of comments
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3376
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3377 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
3378 num_spalettes);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3379
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3380 palette_ptr - array of png_sPLT_struct structures
3381 to be added to the list of palettes
3382 in the info structure.
3383 num_spalettes - number of palette structures to be
3384 added.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3385
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3386 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
3387 unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3388
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3389 offset_x - positive offset from the left
3390 edge of the screen
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3391
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3392 offset_y - positive offset from the top
3393 edge of the screen
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3394
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3395 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
3396
3397 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
3398 unit_type);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3399
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3400 res_x - pixels/unit physical resolution
3401 in x direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3402
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3403 res_y - pixels/unit physical resolution
3404 in y direction
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3405
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3406 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3407 PNG_RESOLUTION_METER
3408
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3409 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3410
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3411 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3412
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3413 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3414
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3415 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3416 (width and height are doubles)
3417
3418 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3419
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3420 unit - physical scale units (an integer)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3421
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3422 width - width of a pixel in physical scale units
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]3423 expressed as a string
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3424
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3425 height - height of a pixel in physical scale units
3426 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3427
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3428 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
3429 num_unknowns)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3430
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3431 unknowns - array of png_unknown_chunk
3432 structures holding unknown chunks
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3433 unknowns[i].name - name of unknown chunk
3434 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]3435 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3436 unknowns[i].location - position to write chunk in file
3437 0: do not write chunk
3438 PNG_HAVE_IHDR: before PLTE
3439 PNG_HAVE_PLTE: before IDAT
3440 PNG_AFTER_IDAT: after IDAT
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3441
3442The "location" member is set automatically according to
3443what part of the output file has already been written.
3444You can change its value after calling png_set_unknown_chunks()
3445as demonstrated in pngtest.c. Within each of the "locations",
3446the chunks are sequenced according to their position in the
3447structure (that is, the value of "i", which is the order in which
3448the chunk was either read from the input file or defined with
3449png_set_unknown_chunks).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3450
3451A quick word about text and num_text. text is an array of png_text
3452structures. num_text is the number of valid structures in the array.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3453Each png_text structure holds a language code, a keyword, a text value,
3454and a compression type.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3455
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3456The compression types have the same valid numbers as the compression
3457types of the image data. Currently, the only valid number is zero.
3458However, you can store text either compressed or uncompressed, unlike
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3459images, which always have to be compressed. So if you don't want the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3460text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3461Because tEXt and zTXt chunks don't have a language field, if you
3462specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
3463any language code or translated keyword will not be written out.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3464
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]3465Until text gets around a few hundred bytes, it is not worth compressing it.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3466After the text has been written out to the file, the compression type
3467is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
3468so that it isn't written out again at the end (in case you are calling
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3469png_write_end() with the same struct).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3470
3471The keywords that are given in the PNG Specification are:
3472
3473 Title Short (one line) title or
3474 caption for image
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3475
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3476 Author Name of image's creator
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3477
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3478 Description Description of image (possibly long)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3479
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3480 Copyright Copyright notice
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3481
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3482 Creation Time Time of original image creation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3483 (usually RFC 1123 format, see below)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3484
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3485 Software Software used to create the image
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3486
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3487 Disclaimer Legal disclaimer
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3488
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3489 Warning Warning of nature of content
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3490
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3491 Source Device used to create the image
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3492
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3493 Comment Miscellaneous comment; conversion
3494 from other image format
3495
3496The keyword-text pairs work like this. Keywords should be short
3497simple descriptions of what the comment is about. Some typical
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3498keywords are found in the PNG specification, as is some recommendations
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3499on keywords. You can repeat keywords in a file. You can even write
3500some text before the image and some after. For example, you may want
3501to put a description of the image before the image, but leave the
3502disclaimer until after, so viewers working over modem connections
3503don't have to wait for the disclaimer to go over the modem before
3504they start seeing the image. Finally, keywords should be full
3505words, not abbreviations. Keywords and text are in the ISO 8859-1
3506(Latin-1) character set (a superset of regular ASCII) and can not
3507contain NUL characters, and should not contain control or other
3508unprintable characters. To make the comments widely readable, stick
3509with basic ASCII, and avoid machine specific character set extensions
3510like the IBM-PC character set. The keyword must be present, but
3511you can leave off the text string on non-compressed pairs.
3512Compressed pairs must have a text string, as only the text string
3513is compressed anyway, so the compression would be meaningless.
3514
3515PNG supports modification time via the png_time structure. Two
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3516conversion routines are provided, png_convert_from_time_t() for
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3517time_t and png_convert_from_struct_tm() for struct tm. The
3518time_t routine uses gmtime(). You don't have to use either of
3519these, but if you wish to fill in the png_time structure directly,
3520you should provide the time in universal time (GMT) if possible
3521instead of your local time. Note that the year number is the full
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3522year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3523that months start with 1.
3524
3525If you want to store the time of the original image creation, you should
3526use a plain tEXt chunk with the "Creation Time" keyword. This is
3527necessary because the "creation time" of a PNG image is somewhat vague,
3528depending on whether you mean the PNG file, the time the image was
3529created in a non-PNG format, a still photo from which the image was
3530scanned, or possibly the subject matter itself. In order to facilitate
3531machine-readable dates, it is recommended that the "Creation Time"
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3532tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3533although this isn't a requirement. Unlike the tIME chunk, the
3534"Creation Time" tEXt chunk is not expected to be automatically changed
3535by the software. To facilitate the use of RFC 1123 dates, a function
3536png_convert_to_rfc1123(png_timep) is provided to convert from PNG
3537time to an RFC 1123 format string.
3538
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3539.SS Writing unknown chunks
3540
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3541You can use the png_set_unknown_chunks function to queue up chunks
3542for writing. You give it a chunk name, raw data, and a size; that's
3543all there is to it. The chunks will be written by the next following
3544png_write_info_before_PLTE, png_write_info, or png_write_end function.
3545Any chunks previously read into the info structure's unknown-chunk
3546list will also be written out in a sequence that satisfies the PNG
3547specification's ordering rules.
3548
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3549.SS The high-level write interface
3550
3551At this point there are two ways to proceed; through the high-level
3552write interface, or through a sequence of low-level write operations.
3553You can use the high-level interface if your image data is present
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3554in the info structure. All defined output
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3555transformations are permitted, enabled by the following masks.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3556
3557 PNG_TRANSFORM_IDENTITY No transformation
3558 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3559 PNG_TRANSFORM_PACKSWAP Change order of packed
3560 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3561 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3562 PNG_TRANSFORM_SHIFT Normalize pixels to the
3563 sBIT depth
3564 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
3565 to BGRA
3566 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
3567 to AG
3568 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
3569 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3570 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
Glenn Randers-Pehrson1eb14e92008-12-10 07:14:45 -0600[diff] [blame]3571 PNG_TRANSFORM_STRIP_FILLER Strip out filler
3572 bytes (deprecated).
3573 PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
3574 filler bytes
3575 PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
3576 filler bytes
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3577
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3578If you have valid image data in the info structure (you can use
3579png_set_rows() to put image data in the info structure), simply do this:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3580
3581 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
3582
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3583where png_transforms is an integer containing the bitwise OR of some set of
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3584transformation flags. This call is equivalent to png_write_info(),
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3585followed the set of transformations indicated by the transform mask,
3586then png_write_image(), and finally png_write_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3587
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3588(The final parameter of this call is not yet used. Someday it might point
3589to transformation parameters required by some future output transform.)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3590
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]3591You must use png_transforms and not call any png_set_transform() functions
3592when you use png_write_png().
3593
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3594.SS The low-level write interface
3595
3596If you are going the low-level route instead, you are now ready to
3597write all the file information up to the actual image data. You do
3598this with a call to png_write_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3599
3600 png_write_info(png_ptr, info_ptr);
3601
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3602Note that there is one transformation you may need to do before
3603png_write_info(). In PNG files, the alpha channel in an image is the
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3604level of opacity. If your data is supplied as a level of transparency,
3605you can invert the alpha channel before you write it, so that 0 is
3606fully transparent and 255 (in 8-bit or paletted images) or 65535
3607(in 16-bit images) is fully opaque, with
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3608
3609 png_set_invert_alpha(png_ptr);
3610
3611This must appear before png_write_info() instead of later with the
3612other transformations because in the case of paletted images the tRNS
3613chunk data has to be inverted before the tRNS chunk is written. If
3614your image is not a paletted image, the tRNS data (which in such cases
3615represents a single color to be rendered as transparent) won't need to
3616be changed, and you can safely do this transformation after your
3617png_write_info() call.
3618
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]3619If you need to write a private chunk that you want to appear before
3620the PLTE chunk when PLTE is present, you can write the PNG info in
3621two steps, and insert code to write your own chunk between them:
3622
3623 png_write_info_before_PLTE(png_ptr, info_ptr);
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3624 png_set_unknown_chunks(png_ptr, info_ptr, ...);
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]3625 png_write_info(png_ptr, info_ptr);
3626
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3627After you've written the file information, you can set up the library
3628to handle any special transformations of the image data. The various
3629ways to transform the data will be described in the order that they
3630should occur. This is important, as some of these change the color
3631type and/or bit depth of the data, and some others only work on
3632certain color types and bit depths. Even though each transformation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3633checks to see if it has data that it can do something with, you should
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3634make sure to only enable a transformation if it will be valid for the
3635data. For example, don't swap red and blue on grayscale data.
3636
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3637PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]3638the library to strip input data that has 4 or 8 bytes per pixel down
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3639to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
3640bytes per pixel).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3641
3642 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
3643
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3644where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3645PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
3646is stored XRGB or RGBX.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3647
3648PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
3649they can, resulting in, for example, 8 pixels per byte for 1 bit files.
3650If the data is supplied at 1 pixel per byte, use this code, which will
3651correctly pack the pixels into a single byte:
3652
3653 png_set_packing(png_ptr);
3654
3655PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
3656data is of another bit depth, you can write an sBIT chunk into the
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3657file so that decoders can recover the original data if desired.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3658
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3659 /* Set the true bit depth of the image data */
3660 if (color_type & PNG_COLOR_MASK_COLOR)
3661 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3662 sig_bit.red = true_bit_depth;
3663 sig_bit.green = true_bit_depth;
3664 sig_bit.blue = true_bit_depth;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3665 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3666
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3667 else
3668 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3669 sig_bit.gray = true_bit_depth;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3670 }
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3671
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3672 if (color_type & PNG_COLOR_MASK_ALPHA)
3673 {
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3674 sig_bit.alpha = true_bit_depth;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3675 }
3676
3677 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
3678
3679If the data is stored in the row buffer in a bit depth other than
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3680one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3681this will scale the values to appear to be the correct bit depth as
3682is required by PNG.
3683
3684 png_set_shift(png_ptr, &sig_bit);
3685
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]3686PNG files store 16-bit pixels in network byte order (big-endian,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3687ie. most significant bits first). This code would be used if they are
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3688supplied the other way (little-endian, i.e. least significant bits
3689first, the way PCs store them):
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3690
3691 if (bit_depth > 8)
3692 png_set_swap(png_ptr);
3693
3694If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
3695need to change the order the pixels are packed into bytes, you can use:
3696
3697 if (bit_depth < 8)
3698 png_set_packswap(png_ptr);
3699
3700PNG files store 3 color pixels in red, green, blue order. This code
3701would be used if they are supplied as blue, green, red:
3702
3703 png_set_bgr(png_ptr);
3704
3705PNG files describe monochrome as black being zero and white being
3706one. This code would be used if the pixels are supplied with this reversed
3707(black being one and white being zero):
3708
3709 png_set_invert_mono(png_ptr);
3710
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3711Finally, you can write your own transformation function if none of
3712the existing ones meets your needs. This is done by setting a callback
3713with
3714
3715 png_set_write_user_transform_fn(png_ptr,
3716 write_transform_fn);
3717
3718You must supply the function
3719
Glenn Randers-Pehrson93215672011-02-13 19:42:19 -0600[diff] [blame]3720 void write_transform_fn(png_structp png_ptr, png_row_infop
3721 row_info, png_bytep data)
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3722
3723See pngtest.c for a working example. Your function will be called
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]3724before any of the other transformations are processed. If supported
3725libpng also supplies an information routine that may be called from
3726your callback:
3727
3728 png_get_current_row_number(png_ptr);
John Bowlercd113452011-02-16 06:15:13 -0600[diff] [blame]3729 png_get_current_pass_number(png_ptr);
John Bowlerf19abd62011-01-22 18:29:24 -0600[diff] [blame]3730
John Bowlercd113452011-02-16 06:15:13 -0600[diff] [blame]3731This returns the current row passed to the transform. With interlaced
3732images the value returned is the row in the input sub-image image. Use
3733PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
3734find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
3735
3736The discussion of interlace handling above contains more information on how to
3737use these values.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3738
3739You can also set up a pointer to a user structure for use by your
3740callback function.
3741
3742 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
3743
3744The user_channels and user_depth parameters of this function are ignored
3745when writing; you can set them to zero as shown.
3746
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3747You can retrieve the pointer via the function png_get_user_transform_ptr().
3748For example:
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3749
3750 voidp write_user_transform_ptr =
3751 png_get_user_transform_ptr(png_ptr);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3752
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3753It is possible to have libpng flush any pending output, either manually,
3754or automatically after a certain number of lines have been written. To
3755flush the output stream a single time call:
3756
3757 png_write_flush(png_ptr);
3758
3759and to have libpng flush the output stream periodically after a certain
3760number of scanlines have been written, call:
3761
3762 png_set_flush(png_ptr, nrows);
3763
3764Note that the distance between rows is from the last time png_write_flush()
3765was called, or the first row of the image if it has never been called.
3766So if you write 50 lines, and then png_set_flush 25, it will flush the
3767output on the next scanline, and every 25 lines thereafter, unless
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3768png_write_flush() is called before 25 more lines have been written.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3769If nrows is too small (less than about 10 lines for a 640 pixel wide
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3770RGB image) the image compression may decrease noticeably (although this
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3771may be acceptable for real-time applications). Infrequent flushing will
3772only degrade the compression performance by a few percent over images
3773that do not use flushing.
3774
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3775.SS Writing the image data
3776
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3777That's it for the transformations. Now you can write the image data.
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3778The simplest way to do this is in one function call. If you have the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3779whole image in memory, you can just call png_write_image() and libpng
3780will write the image. You will need to pass in an array of pointers to
3781each row. This function automatically handles interlacing, so you don't
3782need to call png_set_interlace_handling() or call this function multiple
3783times, or any of that other stuff necessary with png_write_rows().
3784
3785 png_write_image(png_ptr, row_pointers);
3786
3787where row_pointers is:
3788
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3789 png_byte *row_pointers[height];
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3790
3791You can point to void or char or whatever you use for pixels.
3792
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]3793If you don't want to write the whole image at once, you can
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3794use png_write_rows() instead. If the file is not interlaced,
3795this is simple:
3796
3797 png_write_rows(png_ptr, row_pointers,
3798 number_of_rows);
3799
3800row_pointers is the same as in the png_write_image() call.
3801
3802If you are just writing one row at a time, you can do this with
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3803a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3804
3805 png_bytep row_pointer = row;
3806
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]3807 png_write_row(png_ptr, row_pointer);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3808
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3809When the file is interlaced, things can get a good deal more complicated.
3810The only currently (as of the PNG Specification version 1.2, dated July
38111999) defined interlacing scheme for PNG files is the "Adam7" interlace
3812scheme, that breaks down an image into seven smaller images of varying
3813size. libpng will build these images for you, or you can do them
3814yourself. If you want to build them yourself, see the PNG specification
3815for details of which pixels to write when.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3816
3817If you don't want libpng to handle the interlacing details, just
3818use png_set_interlace_handling() and call png_write_rows() the
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3819correct number of times to write all the sub-images
3820(png_set_interlace_handling() returns the number of sub-images.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3821
3822If you want libpng to build the sub-images, call this before you start
3823writing any rows:
3824
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3825 number_of_passes = png_set_interlace_handling(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3826
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3827This will return the number of passes needed. Currently, this is seven,
3828but may change if another interlace type is added.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3829
3830Then write the complete image number_of_passes times.
3831
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3832 png_write_rows(png_ptr, row_pointers, number_of_rows);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3833
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]3834Think carefully before you write an interlaced image. Typically code that
3835reads such images reads all the image data into memory, uncompressed, before
3836doing any processing. Only code that can display an image on the fly can
3837take advantage of the interlacing and even then the image has to be exactly
3838the correct size for the output device, because scaling an image requires
3839adjacent pixels and these are not available until all the passes have been
3840read.
3841
3842If you do write an interlaced image you will hardly ever need to handle
3843the interlacing yourself. Call png_set_interlace_handling() and use the
3844approach described above.
3845
3846The only time it is conceivable that you will really need to write an
3847interlaced image pass-by-pass is when you have read one pass by pass and
3848made some pixel-by-pixel transformation to it, as described in the read
3849code above. In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros
3850to determine the size of each sub-image in turn and simply write the rows
3851you obtained from the read code.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3852
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3853.SS Finishing a sequential write
3854
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3855After you are finished writing the image, you should finish writing
3856the file. If you are interested in writing comments or time, you should
3857pass an appropriately filled png_info pointer. If you are not interested,
3858you can pass NULL.
3859
3860 png_write_end(png_ptr, info_ptr);
3861
3862When you are done, you can free all memory used by libpng like this:
3863
3864 png_destroy_write_struct(&png_ptr, &info_ptr);
3865
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3866It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3867point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3868
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3869 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3870
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3871 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3872 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3873 more of
3874 PNG_FREE_PLTE, PNG_FREE_TRNS,
3875 PNG_FREE_HIST, PNG_FREE_ICCP,
3876 PNG_FREE_PCAL, PNG_FREE_ROWS,
3877 PNG_FREE_SCAL, PNG_FREE_SPLT,
3878 PNG_FREE_TEXT, PNG_FREE_UNKN,
3879 or simply PNG_FREE_ALL
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3880
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3881 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3882 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3883
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]3884This function may be safely called when the relevant storage has
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3885already been freed, or has not yet been allocated, or was allocated
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3886by the user and not by libpng, and will in those cases do nothing.
3887The "seq" parameter is ignored if only one item of the selected data
3888type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
3889are allowed for the data type identified in the mask, such as text or
3890sPLT, only the n'th item in the structure is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3891
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3892If you allocated data such as a palette that you passed in to libpng
3893with png_set_*, you must not free it until just before the call to
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3894png_destroy_write_struct().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3895
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3896The default behavior is only to free data that was allocated internally
3897by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3898or so that it will free data that was allocated by the user with png_malloc()
3899or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3900
3901 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3902
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3903 freer - one of
3904 PNG_DESTROY_WILL_FREE_DATA
3905 PNG_SET_WILL_FREE_DATA
3906 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3907
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3908 mask - which data elements are affected
3909 same choices as in png_free_data()
3910
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3911For example, to transfer responsibility for some data from a read structure
3912to a write structure, you could use
3913
3914 png_data_freer(read_ptr, read_info_ptr,
3915 PNG_USER_WILL_FREE_DATA,
3916 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3917
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3918 png_data_freer(write_ptr, write_info_ptr,
3919 PNG_DESTROY_WILL_FREE_DATA,
3920 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3921
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3922thereby briefly reassigning responsibility for freeing to the user but
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]3923immediately afterwards reassigning it once more to the write_destroy
3924function. Having done this, it would then be safe to destroy the read
3925structure and continue to use the PLTE, tRNS, and hIST data in the write
3926structure.
3927
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3928This function only affects data that has already been allocated.
3929You can call this function before calling after the png_set_*() functions
3930to control whether the user or png_destroy_*() is supposed to free the data.
3931When the user assumes responsibility for libpng-allocated data, the
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3932application must use
3933png_free() to free it, and when the user transfers responsibility to libpng
3934for data that the user has allocated, the user must have used png_malloc()
3935or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3936
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3937If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
3938separately, do not transfer responsibility for freeing text_ptr to libpng,
3939because when libpng fills a png_text structure it combines these members with
3940the key member, and png_free_data() will free only text_ptr.key. Similarly,
3941if you transfer responsibility for free'ing text_ptr from libpng to your
3942application, your application must not separately free those members.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3943For a more compact example of writing a PNG image, see the file example.c.
3944
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]3945.SH V. Modifying/Customizing libpng
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3946
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3947There are two issues here. The first is changing how libpng does
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3948standard things like memory allocation, input/output, and error handling.
3949The second deals with more complicated things like adding new chunks,
3950adding new transformations, and generally changing how libpng works.
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]3951Both of those are compile-time issues; that is, they are generally
3952determined at the time the code is written, and there is rarely a need
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3953to provide the user with a means of changing them.
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]3954
3955Memory allocation, input/output, and error handling
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3956
3957All of the memory allocation, input/output, and error handling in libpng
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]3958goes through callbacks that are user-settable. The default routines are
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3959in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]3960these functions, call the appropriate png_set_*_fn() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3961
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3962Memory allocation is done through the functions png_malloc(), png_calloc(),
3963and png_free(). These currently just call the standard C functions.
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]3964png_calloc() calls png_malloc() and then clears the newly
3965allocated memory to zero. There is limited support for certain systems
3966with segmented memory architectures and the types of pointers declared by
3967png.h match this; you will have to use appropriate pointers in your
3968application. Since it is
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]3969unlikely that the method of handling memory allocation on a platform
3970will change between applications, these functions must be modified in
3971the library at compile time. If you prefer to use a different method
3972of allocating and freeing data, you can use png_create_read_struct_2() or
3973png_create_write_struct_2() to register your own functions as described
3974above. These functions also provide a void pointer that can be retrieved
3975via
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3976
3977 mem_ptr=png_get_mem_ptr(png_ptr);
3978
3979Your replacement memory functions must have prototypes as follows:
3980
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3981 png_voidp malloc_fn(png_structp png_ptr,
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]3982 png_alloc_size_t size);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]3983
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3984 void free_fn(png_structp png_ptr, png_voidp ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3985
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3986Your malloc_fn() must return NULL in case of failure. The png_malloc()
3987function will normally call png_error() if it receives a NULL from the
3988system memory allocator or from your replacement malloc_fn().
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]3989
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]3990Your free_fn() will never be called with a NULL ptr, since libpng's
3991png_free() checks for NULL before calling free_fn().
3992
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3993Input/Output in libpng is done through png_read() and png_write(),
3994which currently just call fread() and fwrite(). The FILE * is stored in
3995png_struct and is initialized via png_init_io(). If you wish to change
3996the method of I/O, the library supplies callbacks that you can set
3997through the function png_set_read_fn() and png_set_write_fn() at run
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]3998time, instead of calling the png_init_io() function. These functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3999also provide a void pointer that can be retrieved via the function
4000png_get_io_ptr(). For example:
4001
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]4002 png_set_read_fn(png_structp read_ptr,
4003 voidp read_io_ptr, png_rw_ptr read_data_fn)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4004
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]4005 png_set_write_fn(png_structp write_ptr,
4006 voidp write_io_ptr, png_rw_ptr write_data_fn,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4007 png_flush_ptr output_flush_fn);
4008
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]4009 voidp read_io_ptr = png_get_io_ptr(read_ptr);
4010 voidp write_io_ptr = png_get_io_ptr(write_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4011
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4012The replacement I/O functions must have prototypes as follows:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4013
4014 void user_read_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]4015 png_bytep data, png_size_t length);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4016
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4017 void user_write_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]4018 png_bytep data, png_size_t length);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4019
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4020 void user_flush_data(png_structp png_ptr);
4021
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4022The user_read_data() function is responsible for detecting and
4023handling end-of-data errors.
4024
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4025Supplying NULL for the read, write, or flush functions sets them back
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4026to using the default C stream functions, which expect the io_ptr to
4027point to a standard *FILE structure. It is probably a mistake
4028to use NULL for one of write_data_fn and output_flush_fn but not both
4029of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
4030It is an error to read from a write stream, and vice versa.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4031
4032Error handling in libpng is done through png_error() and png_warning().
4033Errors handled through png_error() are fatal, meaning that png_error()
4034should never return to its caller. Currently, this is handled via
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4035setjmp() and longjmp() (unless you have compiled libpng with
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]4036PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
Glenn Randers-Pehrson60988072010-04-13 22:11:06 -0500[diff] [blame]4037but you could change this to do things like exit() if you should wish,
Glenn Randers-Pehrson54ac9a92010-04-02 17:06:22 -0500[diff] [blame]4038as long as your function does not return.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4039
4040On non-fatal errors, png_warning() is called
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4041to print a warning message, and then control returns to the calling code.
4042By default png_error() and png_warning() print a message on stderr via
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]4043fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
4044(because you don't want the messages) or PNG_NO_STDIO defined (because
4045fprintf() isn't available). If you wish to change the behavior of the error
4046functions, you will need to set up your own message callbacks. These
4047functions are normally supplied at the time that the png_struct is created.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4048It is also possible to redirect errors and warnings to your own replacement
4049functions after png_create_*_struct() has been called by calling:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4050
4051 png_set_error_fn(png_structp png_ptr,
4052 png_voidp error_ptr, png_error_ptr error_fn,
4053 png_error_ptr warning_fn);
4054
4055 png_voidp error_ptr = png_get_error_ptr(png_ptr);
4056
4057If NULL is supplied for either error_fn or warning_fn, then the libpng
4058default function will be used, calling fprintf() and/or longjmp() if a
4059problem is encountered. The replacement error functions should have
4060parameters as follows:
4061
4062 void user_error_fn(png_structp png_ptr,
4063 png_const_charp error_msg);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4064
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4065 void user_warning_fn(png_structp png_ptr,
4066 png_const_charp warning_msg);
4067
4068The motivation behind using setjmp() and longjmp() is the C++ throw and
4069catch exception handling methods. This makes the code much easier to write,
4070as there is no need to check every return code of every function call.
4071However, there are some uncertainties about the status of local variables
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4072after a longjmp, so the user may want to be careful about doing anything
4073after setjmp returns non-zero besides returning itself. Consult your
4074compiler documentation for more details. For an alternative approach, you
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4075may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net),
4076which is illustrated in pngvalid.c and in contrib/visupng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4077
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4078.SS Custom chunks
4079
4080If you need to read or write custom chunks, you may need to get deeper
4081into the libpng code. The library now has mechanisms for storing
4082and writing chunks of unknown type; you can even declare callbacks
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]4083for custom chunks. However, this may not be good enough if the
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4084library code itself needs to know about interactions between your
4085chunk and existing `intrinsic' chunks.
4086
4087If you need to write a new intrinsic chunk, first read the PNG
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4088specification. Acquire a first level of understanding of how it works.
4089Pay particular attention to the sections that describe chunk names,
4090and look at how other chunks were designed, so you can do things
4091similarly. Second, check out the sections of libpng that read and
4092write chunks. Try to find a chunk that is similar to yours and use
4093it as a template. More details can be found in the comments inside
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4094the code. It is best to handle private or unknown chunks in a generic method,
4095via callback functions, instead of by modifying libpng functions. This
4096is illustrated in pngtest.c, which uses a callback function to handle a
4097private "vpAg" chunk and the new "sTER" chunk, which are both unknown to
4098libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4099
4100If you wish to write your own transformation for the data, look through
4101the part of the code that does the transformations, and check out some of
4102the simpler ones to get an idea of how they work. Try to find a similar
4103transformation to the one you want to add and copy off of it. More details
4104can be found in the comments inside the code itself.
4105
Glenn Randers-Pehrson593fc042011-05-12 22:18:23 -0500[diff] [blame]4106.SS Configuring for 16-bit platforms
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4107
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4108You will want to look into zconf.h to tell zlib (and thus libpng) that
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4109it cannot allocate more then 64K at a time. Even if you can, the memory
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4110won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4111
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4112.SS Configuring for DOS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4113
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4114For DOS users who only have access to the lower 640K, you will
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4115have to limit zlib's memory usage via a png_set_compression_mem_level()
4116call. See zlib.h or zconf.h in the zlib library for more information.
4117
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4118.SS Configuring for Medium Model
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4119
4120Libpng's support for medium model has been tested on most of the popular
4121compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
4122defined, and FAR gets defined to far in pngconf.h, and you should be
4123all set. Everything in the library (except for zlib's structure) is
4124expecting far data. You must use the typedefs with the p or pp on
4125the end for pointers (or at least look at them and be careful). Make
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]4126note that the rows of data are defined as png_bytepp, which is
4127an "unsigned char far * far *".
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4128
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4129.SS Configuring for gui/windowing platforms:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4130
4131You will need to write new error and warning functions that use the GUI
4132interface, as described previously, and set them to be the error and
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]4133warning functions at the time that png_create_*_struct() is called,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4134in order to have them available during the structure initialization.
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4135They can be changed later via png_set_error_fn(). On some compilers,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4136you may also have to change the memory allocators (png_malloc, etc.).
4137
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4138.SS Configuring for compiler xxx:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4139
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]4140All includes for libpng are in pngconf.h. If you need to add, change
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4141or delete an include, this is the place to do it.
4142The includes that are not needed outside libpng are placed in pngpriv.h,
4143which is only used by the routines inside libpng itself.
4144The files in libpng proper only include pngpriv.h and png.h, which
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]4145%14%in turn includes pngconf.h.
4146in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
4147As of libpng-1.5.0, pngpriv.h also includes three other private header
4148files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
4149that previously appeared in the public headers.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4150
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4151.SS Configuring zlib:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4152
4153There are special functions to configure the compression. Perhaps the
4154most useful one changes the compression level, which currently uses
4155input compression values in the range 0 - 9. The library normally
4156uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
4157have shown that for a large majority of images, compression values in
4158the range 3-6 compress nearly as well as higher levels, and do so much
4159faster. For online applications it may be desirable to have maximum speed
4160(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
4161specify no compression (Z_NO_COMPRESSION = 0), but this would create
4162files larger than just storing the raw bitmap. You can specify the
4163compression level by calling:
4164
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]4165 #include zlib.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4166 png_set_compression_level(png_ptr, level);
4167
4168Another useful one is to reduce the memory level used by the library.
4169The memory level defaults to 8, but it can be lowered if you are
4170short on memory (running DOS, for example, where you only have 640K).
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4171Note that the memory level does have an effect on compression; among
4172other things, lower levels will result in sections of incompressible
4173data being emitted in smaller stored blocks, with a correspondingly
4174larger relative overhead of up to 15% in the worst case.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4175
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]4176 #include zlib.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4177 png_set_compression_mem_level(png_ptr, level);
4178
4179The other functions are for configuring zlib. They are not recommended
4180for normal use and may result in writing an invalid PNG file. See
4181zlib.h for more information on what these mean.
4182
Glenn Randers-Pehrson38734ee2011-03-03 06:23:31 -0600[diff] [blame]4183 #include zlib.h
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4184 png_set_compression_strategy(png_ptr,
4185 strategy);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4186
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4187 png_set_compression_window_bits(png_ptr,
4188 window_bits);
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4189
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4190 png_set_compression_method(png_ptr, method);
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]4191
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4192 png_set_compression_buffer_size(png_ptr, size);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4193
Glenn Randers-Pehrson7a287242011-07-26 12:03:11 -0500[diff] [blame]4194As of libpng version 1.5.4, additional APIs became
4195available to set these separately for non-IDAT
4196compressed chunks such as zTXt, iTXt, and iCCP:
4197
4198 #include zlib.h
4199 #if PNG_LIBPNG_VER <= 10504
4200 png_set_text_compression_level(png_ptr, level);
4201
4202 png_set_text_compression_mem_level(png_ptr, level);
4203
4204 png_set_text_compression_strategy(png_ptr,
4205 strategy);
4206
4207 png_set_text_compression_window_bits(png_ptr,
4208 window_bits);
4209
4210 png_set_text_compression_method(png_ptr, method);
4211 #endif
4212
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4213.SS Controlling row filtering
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4214
4215If you want to control whether libpng uses filtering or not, which
4216filters are used, and how it goes about picking row filters, you
4217can call one of these functions. The selection and configuration
4218of row filters can have a significant impact on the size and
4219encoding speed and a somewhat lesser impact on the decoding speed
4220of an image. Filtering is enabled by default for RGB and grayscale
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4221images (with and without alpha), but not for paletted images nor
4222for any images with bit depths less than 8 bits/pixel.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4223
4224The 'method' parameter sets the main filtering method, which is
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]4225currently only '0' in the PNG 1.2 specification. The 'filters'
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4226parameter sets which filter(s), if any, should be used for each
4227scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
4228to turn filtering on and off, respectively.
4229
4230Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
4231PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]4232ORed together with '|' to specify one or more filters to use.
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4233These filters are described in more detail in the PNG specification.
4234If you intend to change the filter type during the course of writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4235the image, you should start with flags set for all of the filters
4236you intend to use so that libpng can initialize its internal
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4237structures appropriately for all of the filter types. (Note that this
4238means the first row must always be adaptively filtered, because libpng
4239currently does not allocate the filter buffers until png_write_row()
4240is called for the first time.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4241
4242 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]4243 PNG_FILTER_UP | PNG_FILTER_AVG |
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4244 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4245
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4246 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
4247 filters);
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]4248 The second parameter can also be
4249 PNG_INTRAPIXEL_DIFFERENCING if you are
4250 writing a PNG to be embedded in a MNG
4251 datastream. This parameter must be the
4252 same as the value of filter_method used
4253 in png_set_IHDR().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4254
4255It is also possible to influence how libpng chooses from among the
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4256available filters. This is done in one or both of two ways - by
4257telling it how important it is to keep the same filter for successive
4258rows, and by telling it the relative computational costs of the filters.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4259
4260 double weights[3] = {1.5, 1.3, 1.1},
4261 costs[PNG_FILTER_VALUE_LAST] =
4262 {1.0, 1.3, 1.3, 1.5, 1.7};
4263
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]4264 png_set_filter_heuristics(png_ptr,
4265 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4266 weights, costs);
4267
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4268The weights are multiplying factors that indicate to libpng that the
4269row filter should be the same for successive rows unless another row filter
4270is that many times better than the previous filter. In the above example,
4271if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4272"sum of absolute differences" 1.5 x 1.3 times higher than other filters
4273and still be chosen, while the NONE filter could have a sum 1.1 times
4274higher than other filters and still be chosen. Unspecified weights are
4275taken to be 1.0, and the specified weights should probably be declining
4276like those above in order to emphasize recent filters over older filters.
4277
4278The filter costs specify for each filter type a relative decoding cost
4279to be considered when selecting row filters. This means that filters
4280with higher costs are less likely to be chosen over filters with lower
4281costs, unless their "sum of absolute differences" is that much smaller.
4282The costs do not necessarily reflect the exact computational speeds of
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]4283the various filters, since this would unduly influence the final image
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4284size.
4285
4286Note that the numbers above were invented purely for this example and
4287are given only to help explain the function usage. Little testing has
4288been done to find optimum values for either the costs or the weights.
4289
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4290.SS Removing unwanted object code
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4291
4292There are a bunch of #define's in pngconf.h that control what parts of
4293libpng are compiled. All the defines end in _SUPPORTED. If you are
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]4294never going to use a capability, you can change the #define to #undef
4295before recompiling libpng and save yourself code and data space, or
4296you can turn off individual capabilities with defines that begin with
4297PNG_NO_.
4298
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4299In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
4300
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]4301You can also turn all of the transforms and ancillary chunk capabilities
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]4302off en masse with compiler directives that define
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]4303PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
4304or all four,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4305along with directives to turn on any of the capabilities that you do
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4306want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
4307transformations but still leave the library fully capable of reading
4308and writing PNG files with all known public chunks. Use of the
4309PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
4310that is incapable of reading or writing ancillary chunks. If you are
4311not using the progressive reading capability, you can turn that off
4312with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
4313capability, which you'll still have).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4314
4315All the reading and writing specific code are in separate files, so the
4316linker should only grab the files it needs. However, if you want to
4317make sure, or if you are building a stand alone library, all the
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4318reading files start with "pngr" and all the writing files start with "pngw".
4319The files that don't match either (like png.c, pngtrans.c, etc.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4320are used for both reading and writing, and always need to be included.
4321The progressive reader is in pngpread.c
4322
4323If you are creating or distributing a dynamically linked library (a .so
4324or DLL file), you should not remove or disable any parts of the library,
4325as this will cause applications linked with different versions of the
4326library to fail if they call functions not available in your library.
4327The size of the library itself should not be an issue, because only
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4328those sections that are actually used will be loaded into memory.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4329
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]4330.SS Requesting debug printout
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4331
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4332The macro definition PNG_DEBUG can be used to request debugging
4333printout. Set it to an integer value in the range 0 to 3. Higher
4334numbers result in increasing amounts of debugging information. The
4335information is printed to the "stderr" file, unless another file
4336name is specified in the PNG_DEBUG_FILE macro definition.
4337
4338When PNG_DEBUG > 0, the following functions (macros) become available:
4339
4340 png_debug(level, message)
4341 png_debug1(level, message, p1)
4342 png_debug2(level, message, p1, p2)
4343
4344in which "level" is compared to PNG_DEBUG to decide whether to print
4345the message, "message" is the formatted string to be printed,
4346and p1 and p2 are parameters that are to be embedded in the string
4347according to printf-style formatting directives. For example,
4348
4349 png_debug1(2, "foo=%d\n", foo);
4350
4351is expanded to
4352
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4353 if (PNG_DEBUG > 2)
4354 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4355
4356When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
4357can still use PNG_DEBUG to control your own debugging:
4358
4359 #ifdef PNG_DEBUG
4360 fprintf(stderr, ...
4361 #endif
4362
4363When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
4364having level = 0 will be printed. There aren't any such statements in
4365this version of libpng, but if you insert some they will be printed.
4366
Glenn Randers-Pehrson56f63962008-10-06 10:16:17 -0500[diff] [blame]4367.SH VI. MNG support
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]4368
4369The MNG specification (available at http://www.libpng.org/pub/mng) allows
4370certain extensions to PNG for PNG images that are embedded in MNG datastreams.
4371Libpng can support some of these extensions. To enable them, use the
4372png_permit_mng_features() function:
4373
4374 feature_set = png_permit_mng_features(png_ptr, mask)
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4375
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4376 mask is a png_uint_32 containing the bitwise OR of the
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]4377 features you want to enable. These include
4378 PNG_FLAG_MNG_EMPTY_PLTE
4379 PNG_FLAG_MNG_FILTER_64
4380 PNG_ALL_MNG_FEATURES
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4381
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]4382 feature_set is a png_uint_32 that is the bitwise AND of
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]4383 your mask with the set of MNG features that is
4384 supported by the version of libpng that you are using.
4385
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]4386It is an error to use this function when reading or writing a standalone
4387PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
Glenn Randers-Pehrsonf05f8032000-12-23 14:27:39 -0600[diff] [blame]4388in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
4389and the MHDR and MEND chunks. Libpng does not provide support for these
4390or any other MNG chunks; your application must provide its own support for
4391them. You may wish to consider using libmng (available at
4392http://www.libmng.com) instead.
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]4393
Glenn Randers-Pehrson8fb550c2009-03-21 08:15:32 -0500[diff] [blame]4394.SH VII. Changes to Libpng from version 0.88
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4395
4396It should be noted that versions of libpng later than 0.96 are not
4397distributed by the original libpng author, Guy Schalnat, nor by
4398Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
4399distributed versions 0.89 through 0.96, but rather by another member
4400of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
4401still alive and well, but they have moved on to other things.
4402
4403The old libpng functions png_read_init(), png_write_init(),
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]4404png_info_init(), png_read_destroy(), and png_write_destroy() have been
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]4405moved to PNG_INTERNAL in version 0.95 to discourage their use. These
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4406functions will be removed from libpng version 1.4.0.
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]4407
4408The preferred method of creating and initializing the libpng structures is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4409via the png_create_read_struct(), png_create_write_struct(), and
4410png_create_info_struct() because they isolate the size of the structures
4411from the application, allow version error checking, and also allow the
4412use of custom error handling routines during the initialization, which
4413the old functions do not. The functions png_read_destroy() and
4414png_write_destroy() do not actually free the memory that libpng
4415allocated for these structs, but just reset the data structures, so they
4416can be used instead of png_destroy_read_struct() and
4417png_destroy_write_struct() if you feel there is too much system overhead
4418allocating and freeing the png_struct for each image read.
4419
4420Setting the error callbacks via png_set_message_fn() before
4421png_read_init() as was suggested in libpng-0.88 is no longer supported
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]4422because this caused applications that do not use custom error functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4423to fail if the png_ptr was not initialized to zero. It is still possible
4424to set the error callbacks AFTER png_read_init(), or to change them with
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]4425png_set_error_fn(), which is essentially the same function, but with a new
4426name to force compilation errors with applications that try to use the old
4427method.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]4428
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4429Starting with version 1.0.7, you can find out which version of the library
4430you are using at run-time:
4431
4432 png_uint_32 libpng_vn = png_access_version_number();
4433
4434The number libpng_vn is constructed from the major version, minor
4435version with leading zero, and release number with leading zero,
4436(e.g., libpng_vn for version 1.0.7 is 10007).
4437
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]4438Note that this function does not take a png_ptr, so you can call it
4439before you've created one.
4440
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]4441You can also check which version of png.h you used when compiling your
4442application:
4443
4444 png_uint_32 application_vn = PNG_LIBPNG_VER;
4445
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4446.SH VIII. Changes to Libpng from version 1.0.x to 1.2.x
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]4447
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4448Support for user memory management was enabled by default. To
4449accomplish this, the functions png_create_read_struct_2(),
4450png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
4451png_malloc_default(), and png_free_default() were added.
4452
Glenn Randers-Pehrsond6ea40a2009-11-02 07:32:00 -0600[diff] [blame]4453Support for the iTXt chunk has been enabled by default as of
4454version 1.2.41.
4455
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4456Support for certain MNG features was enabled.
4457
4458Support for numbered error messages was added. However, we never got
4459around to actually numbering the error messages. The function
4460png_set_strip_error_numbers() was added (Note: the prototype for this
4461function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
4462builds of libpng-1.2.15. It was restored in libpng-1.2.36).
4463
4464The png_malloc_warn() function was added at libpng-1.2.3. This issues
4465a png_warning and returns NULL instead of aborting when it fails to
4466acquire the requested memory allocation.
4467
4468Support for setting user limits on image width and height was enabled
4469by default. The functions png_set_user_limits(), png_get_user_width_max(),
4470and png_get_user_height_max() were added at libpng-1.2.6.
4471
4472The png_set_add_alpha() function was added at libpng-1.2.7.
4473
4474The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
4475Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
4476tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
4477deprecated.
4478
4479A number of macro definitions in support of runtime selection of
4480assembler code features (especially Intel MMX code support) were
4481added at libpng-1.2.0:
4482
4483 PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
4484 PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
4485 PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
4486 PNG_ASM_FLAG_MMX_READ_INTERLACE
4487 PNG_ASM_FLAG_MMX_READ_FILTER_SUB
4488 PNG_ASM_FLAG_MMX_READ_FILTER_UP
4489 PNG_ASM_FLAG_MMX_READ_FILTER_AVG
4490 PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
4491 PNG_ASM_FLAGS_INITIALIZED
4492 PNG_MMX_READ_FLAGS
4493 PNG_MMX_FLAGS
4494 PNG_MMX_WRITE_FLAGS
4495 PNG_MMX_FLAGS
4496
4497We added the following functions in support of runtime
4498selection of assembler code features:
4499
4500 png_get_mmx_flagmask()
4501 png_set_mmx_thresholds()
4502 png_get_asm_flags()
4503 png_get_mmx_bitdepth_threshold()
4504 png_get_mmx_rowbytes_threshold()
4505 png_set_asm_flags()
4506
4507We replaced all of these functions with simple stubs in libpng-1.2.20,
4508when the Intel assembler code was removed due to a licensing issue.
4509
Glenn Randers-Pehrson3d893a02009-08-31 13:32:46 -0500[diff] [blame]4510These macros are deprecated:
4511
4512 PNG_READ_TRANSFORMS_NOT_SUPPORTED
4513 PNG_PROGRESSIVE_READ_NOT_SUPPORTED
4514 PNG_NO_SEQUENTIAL_READ_SUPPORTED
4515 PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
4516 PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
4517 PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
4518
4519They have been replaced, respectively, by:
4520
4521 PNG_NO_READ_TRANSFORMS
4522 PNG_NO_PROGRESSIVE_READ
4523 PNG_NO_SEQUENTIAL_READ
4524 PNG_NO_WRITE_TRANSFORMS
4525 PNG_NO_READ_ANCILLARY_CHUNKS
4526 PNG_NO_WRITE_ANCILLARY_CHUNKS
4527
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4528PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
4529deprecated since libpng-1.0.16 and libpng-1.2.6.
4530
4531The function
4532 png_check_sig(sig, num)
4533was replaced with
4534 !png_sig_cmp(sig, 0, num)
4535It has been deprecated since libpng-0.90.
4536
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4537The function
4538 png_set_gray_1_2_4_to_8()
4539which also expands tRNS to alpha was replaced with
4540 png_set_expand_gray_1_2_4_to_8()
4541which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4542
Glenn Randers-Pehrsond740c842009-11-04 19:01:54 -0600[diff] [blame]4543.SH IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
4544
4545Private libpng prototypes and macro definitions were moved from
4546png.h and pngconf.h into a new pngpriv.h header file.
4547
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4548Functions png_set_benign_errors(), png_benign_error(), and
4549png_chunk_benign_error() were added.
4550
4551Support for setting the maximum amount of memory that the application
4552will allocate for reading chunks was added, as a security measure.
4553The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
4554were added to the library.
4555
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]4556We implemented support for I/O states by adding png_ptr member io_state
4557and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4558
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]4559We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
4560input transforms.
4561
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]4562Checking for and reporting of errors in the IHDR chunk is more thorough.
4563
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4564Support for global arrays was removed, to improve thread safety.
4565
4566Some obsolete/deprecated macros and functions have been removed.
4567
4568Typecasted NULL definitions such as
4569 #define png_voidp_NULL (png_voidp)NULL
4570were eliminated. If you used these in your application, just use
4571NULL instead.
4572
4573The png_struct and info_struct members "trans" and "trans_values" were
4574changed to "trans_alpha" and "trans_color", respectively.
4575
4576The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4577were removed.
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4578
4579The PNG_1_0_X and PNG_1_2_X macros were eliminated.
4580
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]4581The PNG_LEGACY_SUPPORTED macro was eliminated.
4582
4583Many WIN32_WCE #ifdefs were removed.
4584
4585The functions png_read_init(info_ptr), png_write_init(info_ptr),
4586png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
4587have been removed. They have been deprecated since libpng-0.95.
4588
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4589The png_permit_empty_plte() was removed. It has been deprecated
4590since libpng-1.0.9. Use png_permit_mng_features() instead.
4591
4592We removed the obsolete stub functions png_get_mmx_flagmask(),
4593png_set_mmx_thresholds(), png_get_asm_flags(),
4594png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
4595png_set_asm_flags(), and png_mmx_supported()
4596
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4597We removed the obsolete png_check_sig(), png_memcpy_check(), and
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]4598png_memset_check() functions. Instead use !png_sig_cmp(), memcpy(),
4599and memset(), respectively.
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4600
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4601The function png_set_gray_1_2_4_to_8() was removed. It has been
4602deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
4603png_set_expand_gray_1_2_4_to_8() because the former function also
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4604expanded any tRNS chunk to an alpha channel.
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4605
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4606Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
4607were added and are used by default instead of the corresponding
4608functions. Unfortunately,
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4609from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4610function) incorrectly returned a value of type png_uint_32.
4611
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4612We changed the prototype for png_malloc() from
4613 png_malloc(png_structp png_ptr, png_uint_32 size)
4614to
4615 png_malloc(png_structp png_ptr, png_alloc_size_t size)
4616
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]4617This also applies to the prototype for the user replacement malloc_fn().
4618
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4619The png_calloc() function was added and is used in place of
Glenn Randers-Pehrson2be8b642010-07-29 19:09:18 -0500[diff] [blame]4620of "png_malloc(); memset();" except in the case in png_read_png()
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4621where the array consists of pointers; in this case a "for" loop is used
4622after the png_malloc() to set the pointers to NULL, to give robust.
4623behavior in case the application runs out of memory part-way through
4624the process.
4625
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4626We changed the prototypes of png_get_compression_buffer_size() and
4627png_set_compression_buffer_size() to work with png_size_t instead of
4628png_uint_32.
4629
Glenn Randers-Pehrson45af8192009-12-30 08:37:29 -0600[diff] [blame]4630Support for numbered error messages was removed by default, since we
4631never got around to actually numbering the error messages. The function
4632png_set_strip_error_numbers() was removed from the library by default.
4633
4634The png_zalloc() and png_zfree() functions are no longer exported.
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4635The png_zalloc() function no longer zeroes out the memory that it
4636allocates.
4637
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]4638Support for dithering was disabled by default in libpng-1.4.0, because
Glenn Randers-Pehrson9f1cd702011-04-16 19:40:23 -0500[diff] [blame]4639it has not been well tested and doesn't actually "dither".
4640The code was not
Glenn Randers-Pehrson3cd7cff2010-04-16 19:27:08 -0500[diff] [blame]4641removed, however, and could be enabled by building libpng with
4642PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
4643was reenabled, but the function was renamed png_set_quantize() to
4644reflect more accurately what it actually does. At the same time,
4645the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4646PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
4647was renamed to PNG_READ_QUANTIZE_SUPPORTED.
Glenn Randers-Pehrson60988072010-04-13 22:11:06 -0500[diff] [blame]4648
Glenn Randers-Pehrson6a9c2ce2009-03-27 19:30:10 -0500[diff] [blame]4649We removed the trailing '.' from the warning and error messages.
4650
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4651.SH X. Changes to Libpng from version 1.4.x to 1.5.x
4652
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4653From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
Glenn Randers-Pehrson5b40b012010-11-25 07:16:29 -0600[diff] [blame]4654function) incorrectly returned a value of type png_uint_32.
4655
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4656A. Changes that affect users of libpng
4657
4658There are no substantial API changes between the non-deprecated parts of
Glenn Randers-Pehrson5a956a72011-12-22 14:23:37 -0600[diff] [blame]4659the 1.4.5 API and the 1.5.0 API; however the ability to directly access
4660members of the main libpng control structures, png_struct and png_info,
4661deprecated in earlier versions of libpng, has been completely removed from
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4662libpng 1.5.
4663
Glenn Randers-Pehrson5a956a72011-12-22 14:23:37 -0600[diff] [blame]4664We no longer include zlib.h in png.h. The include statement has been moved
4665to pngstruct.h, where it is not accessible by applications. Applications that
4666need access to information in zlib.h will need to add the '#include "zlib.h"'
4667directive. It does not matter whether this is placed prior to or after
Glenn Randers-Pehrson00879b12011-01-15 19:25:34 -0600[diff] [blame]4668the '"#include png.h"' directive.
4669
4670We moved the png_strcpy(), png_strncpy(), png_strlen(), png_memcpy(),
4671png_memcmp(), png_sprintf, and png_memcpy() macros into a private
Glenn Randers-Pehrson5a956a72011-12-22 14:23:37 -0600[diff] [blame]4672header file (pngpriv.h) that is not accessible by applications.
Glenn Randers-Pehrson00879b12011-01-15 19:25:34 -0600[diff] [blame]4673
Glenn Randers-Pehrson9d23b402011-01-08 10:42:01 -0600[diff] [blame]4674In png_get_iCCP, the type of "profile" was changed from png_charpp
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4675to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
Glenn Randers-Pehrson9d23b402011-01-08 10:42:01 -0600[diff] [blame]4676
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4677There are changes of form in png.h, including new and changed macros to
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]4678declare parts of the API. Some API functions with arguments that are
4679pointers to data not modified within the function have been corrected to
4680declare these arguments with PNG_CONST.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4681
4682Much of the internal use of C macros to control the library build has also
4683changed and some of this is visible in the exported header files, in
4684particular the use of macros to control data and API elements visible
4685during application compilation may require significant revision to
4686application code. (It is extremely rare for an application to do this.)
4687
4688Any program that compiled against libpng 1.4 and did not use deprecated
4689features or access internal library structures should compile and work
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]4690against libpng 1.5, except for the change in the prototype for
4691png_get_iCCP() and png_set_iCCP() API functions mentioned above.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4692
Glenn Randers-Pehrson6e974102010-12-19 16:44:22 -0600[diff] [blame]4693libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
4694interlaced images. The macros return the number of rows and columns in
4695each pass and information that can be used to de-interlace and (if
4696absolutely necessary) interlace an image.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4697
4698libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls
Glenn Randers-Pehrsond08b6bd2011-02-19 15:50:17 -0600[diff] [blame]4699the application-provided png_longjmp_ptr on the internal, but application
Glenn Randers-Pehrson33ced442011-04-27 14:58:06 -0500[diff] [blame]4700initialized, longjmp buffer. It is provided as a convenience to avoid
4701the need to use the png_jmpbuf macro, which had the unnecessary side
4702effect of resetting the internal png_longjmp_ptr value.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4703
4704libpng 1.5.0 includes a complete fixed point API. By default this is
4705present along with the corresponding floating point API. In general the
4706fixed point API is faster and smaller than the floating point one because
4707the PNG file format used fixed point, not floating point. This applies
4708even if the library uses floating point in internal calculations. A new
4709macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
4710uses floating point arithmetic (the default) or fixed point arithmetic
4711internally for performance critical calculations such as gamma correction.
Glenn Randers-Pehrson00879b12011-01-15 19:25:34 -0600[diff] [blame]4712In some cases, the gamma calculations may produce slightly different
4713results. This has changed the results in png_rgb_to_gray and in alpha
4714composition (png_set_background for example). This applies even if the
4715original image was already linear (gamma == 1.0) and, therefore, it is
4716not necessary to linearize the image. This is because libpng has *not*
4717been changed to optimize that case correctly, yet.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4718
4719Fixed point support for the sCAL chunk comes with an important caveat;
4720the sCAL specification uses a decimal encoding of floating point values
4721and the accuracy of PNG fixed point values is insufficient for
4722representation of these values. Consequently a "string" API
4723(png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
4724arbitrary sCAL chunks in the absence of either the floating point API or
4725internal floating point calculations.
4726
4727Applications no longer need to include the optional distribution header
4728file pngusr.h or define the corresponding macros during application
4729build in order to see the correct variant of the libpng API. From 1.5.0
4730application code can check for the corresponding _SUPPORTED macro:
4731
4732#ifdef PNG_INCH_CONVERSIONS_SUPPORTED
4733 /* code that uses the inch conversion APIs. */
4734#endif
4735
4736This macro will only be defined if the inch conversion functions have been
4737compiled into libpng. The full set of macros, and whether or not support
4738has been compiled in, are available in the header file pnglibconf.h.
4739This header file is specific to the libpng build. Notice that prior to
47401.5.0 the _SUPPORTED macros would always have the default definition unless
4741reset by pngusr.h or by explicit settings on the compiler command line.
4742These settings may produce compiler warnings or errors in 1.5.0 because
4743of macro redefinition.
4744
Glenn Randers-Pehrsonc36bb792011-02-12 09:49:07 -0600[diff] [blame]4745From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4746function) incorrectly returned a value of type png_uint_32. libpng 1.5.0
4747is consistent with the implementation in 1.4.5 and 1.2.x (where the macro
4748did not exist.)
4749
4750Applications can now choose whether to use these macros or to call the
4751corresponding function by defining PNG_USE_READ_MACROS or
4752PNG_NO_USE_READ_MACROS before including png.h. Notice that this is
4753only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0
Glenn Randers-Pehrson95ba4172011-09-08 12:21:42 -0500[diff] [blame]4754will lead to a link failure.
Glenn Randers-Pehrson59fa3e92011-01-06 07:07:06 -0600[diff] [blame]4755
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]4756Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]4757when compressing the IDAT data and textual data such as zTXt and iCCP.
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]4758In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
Glenn Randers-Pehrson8eb88332011-04-01 00:16:50 -0500[diff] [blame]4759We added five png_set_text_*() functions for setting the parameters to
4760use with textual data.
4761
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]4762Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
John Bowlerb2bee332011-06-10 23:24:58 -0500[diff] [blame]4763option was off by default, and slightly inaccurate scaling occurred.
Glenn Randers-Pehrsonfb29e512011-06-17 20:38:24 -0500[diff] [blame]4764This option can no longer be turned off, and the choice of accurate
4765or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8()
4766API for accurate scaling or the old png_set_strip_16_to_8() API for simple
4767chopping.
Glenn Randers-Pehrson0cb906d2011-06-11 14:22:22 -0500[diff] [blame]4768
Glenn Randers-Pehrson733b1312011-06-15 13:21:01 -0500[diff] [blame]4769Prior to libpng-1.5.4, the png_set_user_limits() function could only be
Glenn Randers-Pehrson0cb906d2011-06-11 14:22:22 -0500[diff] [blame]4770used to reduce the width and height limits from the value of
4771PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
4772that it could be used to override them. Now this function will reduce or
4773increase the limits.
John Bowlerb2bee332011-06-10 23:24:58 -0500[diff] [blame]4774
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4775B. Changes to the build and configuration of libpng
4776
4777Details of internal changes to the library code can be found in the CHANGES
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4778file and in the GIT repository logs. These will be of no concern to the vast
4779majority of library users or builders, however the few who configure libpng
4780to a non-default feature set may need to change how this is done.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4781
4782There should be no need for library builders to alter build scripts if
4783these use the distributed build support - configure or the makefiles -
4784however users of the makefiles may care to update their build scripts
4785to build pnglibconf.h where the corresponding makefile does not do so.
4786
4787Building libpng with a non-default configuration has changed completely.
4788The old method using pngusr.h should still work correctly even though the
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4789way pngusr.h is used in the build has been changed; however, library
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4790builders will probably want to examine the changes to take advantage of
4791new capabilities and to simplify their build system.
4792
4793B.1 Specific changes to library configuration capabilities
4794
4795The library now supports a complete fixed point implementation and can
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4796thus be used on systems that have no floating point support or very
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4797limited or slow support. Previously gamma correction, an essential part
4798of complete PNG support, required reasonably fast floating point.
4799
4800As part of this the choice of internal implementation has been made
4801independent of the choice of fixed versus floating point APIs and all the
4802missing fixed point APIs have been implemented.
4803
4804The exact mechanism used to control attributes of API functions has
4805changed. A single set of operating system independent macro definitions
4806is used and operating system specific directives are defined in
4807pnglibconf.h
4808
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4809As part of this the mechanism used to choose procedure call standards on
4810those systems that allow a choice has been changed. At present this only
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4811affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4812running on Intel processors. As before, PNGAPI is defined where required
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4813to control the exported API functions; however, two new macros, PNGCBAPI
4814and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
4815(PNGCAPI) for functions that must match a C library prototype (currently
4816only png_longjmp_ptr, which must match the C longjmp function.) The new
4817approach is documented in pngconf.h
4818
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4819Despite these changes, libpng 1.5.0 only supports the native C function
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4820calling standard on those platforms tested so far (__cdecl on Microsoft
4821Windows). This is because the support requirements for alternative
4822calling conventions seem to no longer exist. Developers who find it
4823necessary to set PNG_API_RULE to 1 should advise the mailing list
4824(png-mng-implement) of this and library builders who use Openwatcom and
4825therefore set PNG_API_RULE to 2 should also contact the mailing list.
4826
4827A new test program, pngvalid, is provided in addition to pngtest.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4828pngvalid validates the arithmetic accuracy of the gamma correction
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4829calculations and includes a number of validations of the file format.
4830A subset of the full range of tests is run when "make check" is done
4831(in the 'configure' build.) pngvalid also allows total allocated memory
4832usage to be evaluated and performs additional memory overwrite validation.
4833
4834Many changes to individual feature macros have been made. The following
4835are the changes most likely to be noticed by library builders who
4836configure libpng:
4837
48381) All feature macros now have consistent naming:
4839
4840#define PNG_NO_feature turns the feature off
4841#define PNG_feature_SUPPORTED turns the feature on
4842
4843pnglibconf.h contains one line for each feature macro which is either:
4844
4845#define PNG_feature_SUPPORTED
4846
4847if the feature is supported or:
4848
4849/*#undef PNG_feature_SUPPORTED*/
4850
4851if it is not. Library code consistently checks for the 'SUPPORTED' macro.
Glenn Randers-Pehrsond0797f52011-07-12 10:28:02 -0500[diff] [blame]4852It does not, and libpng applications should not, check for the 'NO' macro
4853which will not normally be defined even if the feature is not supported.
4854The 'NO' macros are only used internally for setting or not setting the
4855corresponding 'SUPPORTED' macros.
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4856
4857Compatibility with the old names is provided as follows:
4858
4859PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
4860
4861And the following definitions disable the corresponding feature:
4862
4863PNG_SETJMP_NOT_SUPPORTED disables SETJMP
4864PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
4865PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
4866PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
4867PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
4868PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
4869
4870Library builders should remove use of the above, inconsistent, names.
4871
48722) Warning and error message formatting was previously conditional on
4873the STDIO feature. The library has been changed to use the
4874CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
4875the library no longer uses the printf(3) functions, even though the
4876default read/write implementations use (FILE) style stdio.h functions.
4877
48783) Three feature macros now control the fixed/floating point decisions:
4879
4880PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
4881
4882PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
4883practice these are normally required internally anyway (because the PNG
4884file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
4885merely stops the function from being exported.
4886
4887PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
4888point implementation or the fixed point one. Typically the fixed point
4889implementation is larger and slower than the floating point implementation
4890on a system that supports floating point, however it may be faster on a
4891system which lacks floating point hardware and therefore uses a software
4892emulation.
4893
48944) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the
4895functions to read and write ints to be disabled independently of
4896PNG_USE_READ_MACROS, which allows libpng to be built with the functions
4897even though the default is to use the macros - this allows applications
4898to choose at app buildtime whether or not to use macros (previously
4899impossible because the functions weren't in the default build.)
4900
4901B.2 Changes to the configuration mechanism
4902
4903Prior to libpng-1.5.0 library builders who needed to configure libpng
4904had either to modify the exported pngconf.h header file to add system
4905specific configuration or had to write feature selection macros into
4906pngusr.h and cause this to be included into pngconf.h by defining
4907PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
4908application built without PNG_USER_CONFIG defined would see the
4909unmodified, default, libpng API and thus would probably fail to link.
4910
4911These mechanisms still work in the configure build and in any makefile
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4912build that builds pnglibconf.h, although the feature selection macros
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4913have changed somewhat as described above. In 1.5.0, however, pngusr.h is
4914processed only once, when the exported header file pnglibconf.h is built.
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4915pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4916build of pnglibconf.h and it is never included in an application build.
4917
4918The rarely used alternative of adding a list of feature macros to the
4919CFLAGS setting in the build also still works, however the macros will be
4920copied to pnglibconf.h and this may produce macro redefinition warnings
4921when the individual C files are compiled.
4922
4923All configuration now only works if pnglibconf.h is built from
4924scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
4925(the original author of awk) maintains C source code of that awk and this
4926and all known later implementations (often called by subtly different
4927names - nawk and gawk for example) are adequate to build pnglibconf.h.
4928The Sun Microsystems (now Oracle) program 'awk' is an earlier version
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4929and does not work; this may also apply to other systems that have a
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]4930functioning awk called 'nawk'.
4931
4932Configuration options are now documented in scripts/pnglibconf.dfa. This
4933file also includes dependency information that ensures a configuration is
4934consistent; that is, if a feature is switched off dependent features are
4935also removed. As a recommended alternative to using feature macros in
4936pngusr.h a system builder may also define equivalent options in pngusr.dfa
4937(or, indeed, any file) and add that to the configuration by setting
4938DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
4939how to do this, and a case where pngusr.h is still required.
4940
Glenn Randers-Pehrson5a956a72011-12-22 14:23:37 -0600[diff] [blame]4941.SH XI. Changes to Libpng from version 1.5.x to 1.6.x
4942
4943We no longer include string.h in png.h. The include statement has been moved
4944to pngpriv.h, where it is not accessible by applications. Applications that
4945need access to information in string.h must add an '#include "string.h"'
4946directive. It does not matter whether this is placed prior to or after
4947the '"#include png.h"' directive.
4948
4949The following API are now DEPRECATED:
4950 png_info_init_3()
4951 png_convert_to_rfc1123() which has been replaced
4952 with png_convert_to_rfc1123_buffer()
4953 png_malloc_default()
4954 png_free_default()
4955
4956The following has been removed:
4957 png_get_io_chunk_name(), which has been replaced
4958 with png_get_io_chunk_type(). The new
4959 function returns a 32-bit integer instead of
4960 a string.
4961
4962A "simplified API" has been added (see documentation in png.h and a simple
4963example in contrib/examples/pngtopng.c)
4964
4965.SH XII. Detecting libpng
Glenn Randers-Pehrson424c9852009-06-02 13:45:15 -0500[diff] [blame]4966
4967The png_get_io_ptr() function has been present since libpng-0.88, has never
4968changed, and is unaffected by conditional compilation macros. It is the
4969best choice for use in configure scripts for detecting the presence of any
Glenn Randers-Pehrson99708d52009-06-29 17:30:00 -0500[diff] [blame]4970libpng version since 0.88. In an autoconf "configure.in" you could use
4971
4972 AC_CHECK_LIB(png, png_get_io_ptr, ...
Glenn Randers-Pehrson424c9852009-06-02 13:45:15 -0500[diff] [blame]4973
Glenn Randers-Pehrson5a956a72011-12-22 14:23:37 -0600[diff] [blame]4974.SH XIII. Source code repository
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]4975
4976Since about February 2009, version 1.2.34, libpng has been under "git" source
4977control. The git repository was built from old libpng-x.y.z.tar.gz files
4978going back to version 0.70. You can access the git repository (read only)
4979at
4980
4981 git://libpng.git.sourceforge.net/gitroot/libpng
4982
4983or you can browse it via "gitweb" at
4984
4985 http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
4986
4987Patches can be sent to glennrp at users.sourceforge.net or to
4988png-mng-implement at lists.sourceforge.net or you can upload them to
4989the libpng bug tracker at
4990
4991 http://libpng.sourceforge.net
4992
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4993We also accept patches built from the tar or zip distributions, and
4994simple verbal discriptions of bug fixes, reported either to the
Glenn Randers-Pehrsona5e55472011-07-12 10:13:32 -0500[diff] [blame]4995SourceForge bug tracker, to the png-mng-implement at lists.sf.net
4996mailing list, or directly to glennrp.
Glenn Randers-Pehrson7bc25012011-01-21 23:29:09 -0600[diff] [blame]4997
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]4998.SH XIV. Coding style
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]4999
5000Our coding style is similar to the "Allman" style, with curly
5001braces on separate lines:
5002
5003 if (condition)
5004 {
5005 action;
5006 }
5007
5008 else if (another condition)
5009 {
5010 another action;
5011 }
5012
5013The braces can be omitted from simple one-line actions:
5014
5015 if (condition)
5016 return (0);
5017
5018We use 3-space indentation, except for continued statements which
5019are usually indented the same as the first line of the statement
5020plus four more spaces.
5021
Glenn Randers-Pehrson5ade7ed2009-09-30 15:11:49 -0500[diff] [blame]5022For macro definitions we use 2-space indentation, always leaving the "#"
5023in the first column.
5024
5025 #ifndef PNG_NO_FEATURE
5026 # ifndef PNG_FEATURE_SUPPORTED
5027 # define PNG_FEATURE_SUPPORTED
5028 # endif
5029 #endif
5030
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5031Comments appear with the leading "/*" at the same indentation as
5032the statement that follows the comment:
5033
5034 /* Single-line comment */
5035 statement;
5036
Glenn Randers-Pehrsone4c706a2010-03-06 14:51:54 -0600[diff] [blame]5037 /* This is a multiple-line
5038 * comment.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5039 */
5040 statement;
5041
Glenn Randers-Pehrsone4c706a2010-03-06 14:51:54 -0600[diff] [blame]5042Very short comments can be placed after the end of the statement
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5043to which they pertain:
5044
5045 statement; /* comment */
5046
5047We don't use C++ style ("//") comments. We have, however,
5048used them in the past in some now-abandoned MMX assembler
5049code.
5050
Glenn Randers-Pehrsonb5444a12009-06-08 08:36:19 -0500[diff] [blame]5051Functions and their curly braces are not indented, and
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5052exported functions are marked with PNGAPI:
5053
5054 /* This is a public function that is visible to
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5055 * application programmers. It does thus-and-so.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5056 */
5057 void PNGAPI
5058 png_exported_function(png_ptr, png_info, foo)
5059 {
5060 body;
5061 }
5062
Glenn Randers-Pehrson416976f2009-07-27 22:16:09 -0500[diff] [blame]5063The prototypes for all exported functions appear in png.h,
5064above the comment that says
5065
5066 /* Maintainer: Put new public prototypes here ... */
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5067
5068We mark all non-exported functions with "/* PRIVATE */"":
5069
5070 void /* PRIVATE */
5071 png_non_exported_function(png_ptr, png_info, foo)
5072 {
5073 body;
5074 }
5075
Glenn Randers-Pehrson416976f2009-07-27 22:16:09 -0500[diff] [blame]5076The prototypes for non-exported functions (except for those in
Glenn Randers-Pehrson5df7edb2009-10-29 23:32:44 -0500[diff] [blame]5077pngtest) appear in
5078pngpriv.h
Glenn Randers-Pehrson416976f2009-07-27 22:16:09 -0500[diff] [blame]5079above the comment that says
5080
5081 /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5082
Glenn Randers-Pehrsoncbbe9a52011-01-29 16:12:11 -0600[diff] [blame]5083To avoid polluting the global namespace, the names of all exported
5084functions and variables begin with "png_", and all publicly visible C
5085preprocessor macros begin with "PNG_". We request that applications that
5086use libpng *not* begin any of their own symbols with either of these strings.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5087
5088We put a space after each comma and after each semicolon
Glenn Randers-Pehrson49a56e72010-12-06 20:06:01 -0600[diff] [blame]5089in "for" statements, and we put spaces before and after each
Glenn Randers-Pehrsone4c706a2010-03-06 14:51:54 -0600[diff] [blame]5090C binary operator and after "for" or "while", and before
5091"?". We don't put a space between a typecast and the expression
5092being cast, nor do we put one between a function name and the
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5093left parenthesis that follows it:
5094
5095 for (i = 2; i > 0; --i)
Glenn Randers-Pehrson67f3b482009-09-23 11:36:28 -0500[diff] [blame]5096 y[i] = a(x) + (int)b;
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5097
Glenn Randers-Pehrsond60c8862009-06-15 21:56:14 -0500[diff] [blame]5098We prefer #ifdef and #ifndef to #if defined() and if !defined()
5099when there is only one macro being tested.
5100
Glenn Randers-Pehrson8db19982011-10-27 16:17:24 -0500[diff] [blame]5101We prefer to express integers that are used as bit masks in hex format,
5102with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100).
5103
Glenn Randers-Pehrson67f3b482009-09-23 11:36:28 -0500[diff] [blame]5104We do not use the TAB character for indentation in the C sources.
5105
Glenn Randers-Pehrson62ca98e2009-12-20 15:14:57 -0600[diff] [blame]5106Lines do not exceed 80 characters.
5107
Glenn Randers-Pehrsonf210a052009-11-12 10:02:24 -0600[diff] [blame]5108Other rules can be inferred by inspecting the libpng source.
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5109
Glenn Randers-Pehrson5a956a72011-12-22 14:23:37 -0600[diff] [blame]5110.SH XV. Y2K Compliance in libpng
Glenn Randers-Pehrson76546822009-05-16 07:25:42 -0500[diff] [blame]5111
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]5112December 30, 2011
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5113
5114Since the PNG Development group is an ad-hoc body, we can't make
5115an official declaration.
5116
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5117This is your unofficial assurance that libpng from version 0.71 and
Glenn Randers-Pehrson67ee8ce2011-12-22 08:21:00 -0600[diff] [blame]5118upward through 1.6.0beta04 are Y2K compliant. It is my belief that earlier
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5119versions were also Y2K compliant.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5120
5121Libpng only has three year fields. One is a 2-byte unsigned integer that
5122will hold years up to 65535. The other two hold the date in text
5123format, and will hold years up to 9999.
5124
5125The integer is
5126 "png_uint_16 year" in png_time_struct.
5127
5128The strings are
5129 "png_charp time_buffer" in png_struct and
5130 "near_time_buffer", which is a local character string in png.c.
5131
5132There are seven time-related functions:
5133
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5134 png_convert_to_rfc_1123() in png.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5135 (formerly png_convert_to_rfc_1152() in error)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5136 png_convert_from_struct_tm() in pngwrite.c, called
5137 in pngwrite.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5138 png_convert_from_time_t() in pngwrite.c
5139 png_get_tIME() in pngget.c
5140 png_handle_tIME() in pngrutil.c, called in pngread.c
5141 png_set_tIME() in pngset.c
5142 png_write_tIME() in pngwutil.c, called in pngwrite.c
5143
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5144All appear to handle dates properly in a Y2K environment. The
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5145png_convert_from_time_t() function calls gmtime() to convert from system
5146clock time, which returns (year - 1900), which we properly convert to
5147the full 4-digit year. There is a possibility that applications using
5148libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5149function, or that they are incorrectly passing only a 2-digit year
5150instead of "year - 1900" into the png_convert_from_struct_tm() function,
5151but this is not under our control. The libpng documentation has always
5152stated that it works with 4-digit years, and the APIs have been
5153documented as such.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5154
5155The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
5156integer to hold the year, and can hold years as large as 65535.
5157
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5158zlib, upon which libpng depends, is also Y2K compliant. It contains
5159no date-related code.
5160
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]5161
5162 Glenn Randers-Pehrson
5163 libpng maintainer
5164 PNG Development Group
5165
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5166.SH NOTE
5167
5168Note about libpng version numbers:
5169
5170Due to various miscommunications, unforeseen code incompatibilities
5171and occasional factors outside the authors' control, version numbering
5172on the library has not always been consistent and straightforward.
5173The following table summarizes matters since version 0.89c, which was
5174the first widely used release:
5175
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5176 source png.h png.h shared-lib
5177 version string int version
5178 ------- ------ ----- ----------
5179 0.89c ("beta 3") 0.89 89 1.0.89
5180 0.90 ("beta 4") 0.90 90 0.90
5181 0.95 ("beta 5") 0.95 95 0.95
5182 0.96 ("beta 6") 0.96 96 0.96
5183 0.97b ("beta 7") 1.00.97 97 1.0.1
5184 0.97c 0.97 97 2.0.97
5185 0.98 0.98 98 2.0.98
5186 0.99 0.99 98 2.0.99
5187 0.99a-m 0.99 99 2.0.99
5188 1.00 1.00 100 2.1.0
5189 1.0.0 1.0.0 100 2.1.0
5190 1.0.0 (from here on, the 100 2.1.0
5191 1.0.1 png.h string is 10001 2.1.0
5192 1.0.1a-e identical to the 10002 from here on, the
5193 1.0.2 source version) 10002 shared library is 2.V
5194 1.0.2a-b 10003 where V is the source
5195 1.0.1 10001 code version except as
5196 1.0.1a-e 10002 2.1.0.1a-e noted.
5197 1.0.2 10002 2.1.0.2
5198 1.0.2a-b 10003 2.1.0.2a-b
5199 1.0.3 10003 2.1.0.3
5200 1.0.3a-d 10004 2.1.0.3a-d
5201 1.0.4 10004 2.1.0.4
5202 1.0.4a-f 10005 2.1.0.4a-f
5203 1.0.5 (+ 2 patches) 10005 2.1.0.5
5204 1.0.5a-d 10006 2.1.0.5a-d
5205 1.0.5e-r 10100 2.1.0.5e-r
5206 1.0.5s-v 10006 2.1.0.5s-v
5207 1.0.6 (+ 3 patches) 10006 2.1.0.6
5208 1.0.6d-g 10007 2.1.0.6d-g
5209 1.0.6h 10007 10.6h
5210 1.0.6i 10007 10.6i
5211 1.0.6j 10007 2.1.0.6j
Glenn Randers-Pehrson25467032011-01-28 11:58:40 -0600[diff] [blame]5212 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5213 1.0.7beta15-18 1 10007 2.1.0.7beta15-18
5214 1.0.7rc1-2 1 10007 2.1.0.7rc1-2
5215 1.0.7 1 10007 2.1.0.7
5216 1.0.8beta1-4 1 10008 2.1.0.8beta1-4
5217 1.0.8rc1 1 10008 2.1.0.8rc1
5218 1.0.8 1 10008 2.1.0.8
5219 1.0.9beta1-6 1 10009 2.1.0.9beta1-6
5220 1.0.9rc1 1 10009 2.1.0.9rc1
5221 1.0.9beta7-10 1 10009 2.1.0.9beta7-10
5222 1.0.9rc2 1 10009 2.1.0.9rc2
5223 1.0.9 1 10009 2.1.0.9
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]5224 1.0.10beta1 1 10010 2.1.0.10beta1
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5225 1.0.10rc1 1 10010 2.1.0.10rc1
Glenn Randers-Pehrson13cfbac2001-03-30 06:42:28 -0600[diff] [blame]5226 1.0.10 1 10010 2.1.0.10
Glenn Randers-Pehrsone1eff582001-04-14 20:15:41 -0500[diff] [blame]5227 1.0.11beta1-3 1 10011 2.1.0.11beta1-3
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]5228 1.0.11rc1 1 10011 2.1.0.11rc1
Glenn Randers-Pehrson32835392001-04-27 08:29:32 -0500[diff] [blame]5229 1.0.11 1 10011 2.1.0.11
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]5230 1.0.12beta1-2 2 10012 2.1.0.12beta1-2
5231 1.0.12rc1 2 10012 2.1.0.12rc1
5232 1.0.12 2 10012 2.1.0.12
5233 1.1.0a-f - 10100 2.1.1.0a-f abandoned
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]5234 1.2.0beta1-2 2 10200 2.1.2.0beta1-2
Glenn Randers-Pehrson5a0be342001-10-18 20:55:13 -0500[diff] [blame]5235 1.2.0beta3-5 3 10200 3.1.2.0beta3-5
5236 1.2.0rc1 3 10200 3.1.2.0rc1
5237 1.2.0 3 10200 3.1.2.0
Glenn Randers-Pehrson5cded0b2001-11-07 07:10:08 -0600[diff] [blame]5238 1.2.1beta-4 3 10201 3.1.2.1beta1-4
Glenn Randers-Pehrsondb3b88d2001-12-04 06:30:43 -0600[diff] [blame]5239 1.2.1rc1-2 3 10201 3.1.2.1rc1-2
5240 1.2.1 3 10201 3.1.2.1
Glenn Randers-Pehrson25228ab2002-03-31 07:33:55 -0600[diff] [blame]5241 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6
Glenn Randers-Pehrsonfcbd7872002-04-07 16:35:38 -0500[diff] [blame]5242 1.0.13beta1 10 10013 10.so.0.1.0.13beta1
5243 1.0.13rc1 10 10013 10.so.0.1.0.13rc1
5244 1.2.2rc1 12 10202 12.so.0.1.2.2rc1
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]5245 1.0.13 10 10013 10.so.0.1.0.13
5246 1.2.2 12 10202 12.so.0.1.2.2
Glenn Randers-Pehrson22f28962002-05-13 18:17:09 -0500[diff] [blame]5247 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6
5248 1.2.3 12 10203 12.so.0.1.2.3
Glenn Randers-Pehrsond020e9d2002-06-28 09:34:00 -0500[diff] [blame]5249 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3
Glenn Randers-Pehrson2ae022d2002-07-01 22:23:46 -0500[diff] [blame]5250 1.2.4rc1 13 10204 12.so.0.1.2.4rc1
Glenn Randers-Pehrson484a8a12002-07-07 19:15:20 -0500[diff] [blame]5251 1.0.14 10 10014 10.so.0.1.0.14
5252 1.2.4 13 10204 12.so.0.1.2.4
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]5253 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
5254 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5255 1.0.15 10 10015 10.so.0.1.0.15
5256 1.2.5 13 10205 12.so.0.1.2.5
5257 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
Glenn Randers-Pehrson37f116a2004-08-15 07:15:39 -0500[diff] [blame]5258 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
5259 1.0.16 10 10016 10.so.0.1.0.16
5260 1.2.6 13 10206 12.so.0.1.2.6
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]5261 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]5262 1.0.17rc1 10 10017 12.so.0.1.0.17rc1
5263 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
Glenn Randers-Pehrson250dfe12004-09-11 21:19:54 -0500[diff] [blame]5264 1.0.17 10 10017 12.so.0.1.0.17
5265 1.2.7 13 10207 12.so.0.1.2.7
Glenn Randers-Pehrson40936072004-11-20 11:18:40 -0600[diff] [blame]5266 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
Glenn Randers-Pehrson584b96e2004-11-29 15:08:00 -0600[diff] [blame]5267 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5
5268 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
Glenn Randers-Pehrson917648e2004-12-02 18:14:51 -0600[diff] [blame]5269 1.0.18 10 10018 12.so.0.1.0.18
5270 1.2.8 13 10208 12.so.0.1.2.8
Glenn Randers-Pehrsone6474622006-03-04 16:50:47 -0600[diff] [blame]5271 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
Glenn Randers-Pehrson4deeb792006-03-22 16:21:59 -0600[diff] [blame]5272 1.2.9beta4-11 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrson3a512032006-03-31 05:29:33 -0600[diff] [blame]5273 1.2.9rc1 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsona7d0c942006-04-14 06:22:52 -0500[diff] [blame]5274 1.2.9 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]5275 1.2.10beta1-7 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson17218292006-04-20 07:20:46 -0500[diff] [blame]5276 1.2.10rc1-2 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson86dc9812006-05-10 07:27:44 -0500[diff] [blame]5277 1.2.10 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]5278 1.4.0beta1-6 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrsond60c8862009-06-15 21:56:14 -0500[diff] [blame]5279 1.2.11beta1-4 13 10210 12.so.0.11[.0]
Glenn Randers-Pehrson3424ee72006-07-12 13:33:47 -0500[diff] [blame]5280 1.4.0beta7-8 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrson701dbaa2006-11-17 09:36:54 -0600[diff] [blame]5281 1.2.11 13 10211 12.so.0.11[.0]
5282 1.2.12 13 10212 12.so.0.12[.0]
5283 1.4.0beta9-14 14 10400 14.so.0.0[.0]
5284 1.2.13 13 10213 12.so.0.13[.0]
Glenn Randers-Pehrson97a9b482008-10-25 20:03:28 -0500[diff] [blame]5285 1.4.0beta15-36 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrsonfa028102009-10-10 06:15:21 -0500[diff] [blame]5286 1.4.0beta37-87 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrson733da8c2009-10-30 00:00:15 -0500[diff] [blame]5287 1.4.0rc01 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrson62ca98e2009-12-20 15:14:57 -0600[diff] [blame]5288 1.4.0beta88-109 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrson67a83db2010-01-01 18:26:18 -0600[diff] [blame]5289 1.4.0rc02-08 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrsondbcfb712009-12-25 14:24:18 -0600[diff] [blame]5290 1.4.0 14 10400 14.so.14.0[.0]
Glenn Randers-Pehrsone3f3c4e2010-02-07 18:08:50 -0600[diff] [blame]5291 1.4.1beta01-03 14 10401 14.so.14.1[.0]
5292 1.4.1rc01 14 10401 14.so.14.1[.0]
Glenn Randers-Pehrson7a5be532010-02-14 07:16:19 -0600[diff] [blame]5293 1.4.1beta04-12 14 10401 14.so.14.1[.0]
Glenn Randers-Pehrsonaaf377c2010-03-08 11:20:30 -0600[diff] [blame]5294 1.4.1 14 10401 14.so.14.1[.0]
Glenn Randers-Pehrson5b3d5542010-06-18 21:55:53 -0500[diff] [blame]5295 1.4.2 14 10402 14.so.14.2[.0]
5296 1.4.3 14 10403 14.so.14.3[.0]
Glenn Randers-Pehrson2776d5e2010-11-21 15:18:02 -0600[diff] [blame]5297 1.4.4 14 10404 14.so.14.4[.0]
Glenn Randers-Pehrsonfd20a5a2010-12-27 08:53:08 -0600[diff] [blame]5298 1.5.0beta01-58 15 10500 15.so.15.0[.0]
Glenn Randers-Pehrson64b863c2011-01-04 09:57:06 -0600[diff] [blame]5299 1.5.0rc01-07 15 10500 15.so.15.0[.0]
Glenn Randers-Pehrsonf5ea1b72011-01-06 06:42:51 -0600[diff] [blame]5300 1.5.0 15 10500 15.so.15.0[.0]
Glenn Randers-Pehrsonef123cc2011-01-28 15:20:34 -0600[diff] [blame]5301 1.5.1beta01-11 15 10501 15.so.15.1[.0]
Glenn Randers-Pehrson3d3aae12011-02-02 22:58:27 -0600[diff] [blame]5302 1.5.1rc01-02 15 10501 15.so.15.1[.0]
5303 1.5.1 15 10501 15.so.15.1[.0]
Glenn Randers-Pehrsonf3dd1cc2011-03-18 22:02:20 -0500[diff] [blame]5304 1.5.2beta01-03 15 10502 15.so.15.2[.0]
Glenn Randers-Pehrson77fd0832011-03-24 08:59:48 -0500[diff] [blame]5305 1.5.2rc01-03 15 10502 15.so.15.2[.0]
Glenn Randers-Pehrsondcc35052011-03-31 11:23:49 -0500[diff] [blame]5306 1.5.2 15 10502 15.so.15.2[.0]
Glenn Randers-Pehrson36edbb52011-06-03 07:15:04 -0500[diff] [blame]5307 1.5.3beta01-10 15 10503 15.so.15.3[.0]
Glenn Randers-Pehrsonfb278732011-06-10 20:43:39 -0500[diff] [blame]5308 1.5.3rc01-02 15 10503 15.so.15.3[.0]
Glenn Randers-Pehrson413138a2011-06-13 22:07:37 -0500[diff] [blame]5309 1.5.3beta11 15 10503 15.so.15.3[.0]
5310 1.5.3 [omitted]
Glenn Randers-Pehrson9daf91e2011-06-22 23:10:36 -0500[diff] [blame]5311 1.5.4beta01-08 15 10504 15.so.15.4[.0]
Glenn Randers-Pehrson78bb9da2011-06-30 18:59:45 -0500[diff] [blame]5312 1.5.4rc01 15 10504 15.so.15.4[.0]
Glenn Randers-Pehrsond404b6d2011-07-07 06:24:57 -0500[diff] [blame]5313 1.5.4 15 10504 15.so.15.4[.0]
Glenn Randers-Pehrson3c2ae602011-09-09 06:02:09 -0500[diff] [blame]5314 1.5.5beta01-08 15 10505 15.so.15.5[.0]
5315 1.5.5rc01 15 10505 15.so.15.5[.0]
Glenn Randers-Pehrson3e2263a2011-09-22 08:40:32 -0500[diff] [blame]5316 1.5.5 15 10505 15.so.15.5[.0]
Glenn Randers-Pehrson93254f62011-10-26 08:36:21 -0500[diff] [blame]5317 1.5.6beta01-07 15 10506 15.so.15.6[.0]
Glenn Randers-Pehrsonbc6726b2011-11-02 22:43:00 -0500[diff] [blame]5318 1.5.6rc01-03 15 10506 15.so.15.6[.0]
5319 1.5.6 15 10506 15.so.15.6[.0]
Glenn Randers-Pehrson36251d32011-11-17 21:14:34 -0600[diff] [blame]5320 1.5.7beta01-05 15 10507 15.so.15.7[.0]
Glenn Randers-Pehrsonb74fb4e2011-12-21 08:37:46 -0600[diff] [blame]5321 1.5.7rc01-03 15 10507 15.so.15.7[.0]
5322 1.5.7 15 10507 15.so.15.7[.0]
Glenn Randers-Pehrson67ee8ce2011-12-22 08:21:00 -0600[diff] [blame]5323 1.6.0beta01-04 16 10600 16.so.16.0[.0]
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5324
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5325Henceforth the source version will match the shared-library minor
5326and patch numbers; the shared-library major version number will be
5327used for changes in backward compatibility, as it is intended. The
5328PNG_PNGLIB_VER macro, which is not used within libpng but is available
5329for applications, is an unsigned integer of the form xyyzz corresponding
5330to the source version x.y.z (leading zeros in y and z). Beta versions
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]5331were given the previous public release number plus a letter, until
5332version 1.0.6j; from then on they were given the upcoming public
5333release number plus "betaNN" or "rcN".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5334
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5335.SH "SEE ALSO"
Glenn Randers-Pehrson4e763f12010-03-03 10:45:50 -0600[diff] [blame]5336.BR "png"(5), " libpngpf"(3), " zlib"(3), " deflate"(5), " " and " zlib"(5)
Glenn Randers-Pehrson7fb32a82010-03-03 09:47:49 -0600[diff] [blame]5337
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5338.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5339.IR libpng :
5340.IP
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]5341http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]5342http://www.libpng.org/pub/png
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5343
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5344.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5345.IR zlib :
5346.IP
5347(generally) at the same location as
5348.I libpng
5349or at
5350.br
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]5351ftp://ftp.info-zip.org/pub/infozip/zlib
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5352
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5353.LP
5354.IR PNG specification: RFC 2083
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5355.IP
5356(generally) at the same location as
5357.I libpng
5358or at
5359.br
5360ftp://ds.internic.net/rfc/rfc2083.txt
5361.br
5362or (as a W3C Recommendation) at
5363.br
5364http://www.w3.org/TR/REC-png.html
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5365
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]5366.LP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5367In the case of any inconsistency between the PNG specification
5368and this library, the specification takes precedence.
5369
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5370.SH AUTHORS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5371This man page: Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]5372<glennrp at users.sourceforge.net>
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5373
5374The contributing authors would like to thank all those who helped
5375with testing, bug fixes, and patience. This wouldn't have been
5376possible without all of you.
5377
5378Thanks to Frank J. T. Wojcik for helping with the documentation.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]5379
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]5380Libpng version 1.6.0beta04 - December 30, 2011:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5381Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]5382Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5383
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5384Supported by the PNG development group
5385.br
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]5386png-mng-implement at lists.sf.net
5387(subscription required; visit
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]5388png-mng-implement at lists.sourceforge.net (subscription required; visit
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]5389https://lists.sourceforge.net/lists/listinfo/png-mng-implement
5390to subscribe).
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5391
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5392.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5393
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]5394(This copy of the libpng notices is provided for your convenience. In case of
5395any discrepancy between this copy and the notices in the file png.h that is
5396included in the libpng distribution, the latter shall prevail.)
5397
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5398If you modify libpng you may insert additional notices immediately following
5399this sentence.
5400
Glenn Randers-Pehrsonbfbf8652009-06-26 21:46:52 -0500[diff] [blame]5401This code is released under the libpng license.
Glenn Randers-Pehrson037023b2009-06-24 10:27:36 -0500[diff] [blame]5402
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]5403libpng versions 1.2.6, August 15, 2004, through 1.6.0beta04, December 30, 2011, are
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame]5404Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5405distributed according to the same disclaimer and license as libpng-1.2.5
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]5406with the following individual added to the list of Contributing Authors
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5407
5408 Cosmin Truta
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]5409
5410libpng versions 1.0.7, July 1, 2000, through 1.2.5 - October 3, 2002, are
Glenn Randers-Pehrsonc6de22d2002-02-23 18:55:25 -0600[diff] [blame]5411Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson32fc5ce2000-07-24 06:34:14 -0500[diff] [blame]5412distributed according to the same disclaimer and license as libpng-1.0.6
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5413with the following individuals added to the list of Contributing Authors
5414
5415 Simon-Pierre Cadieux
5416 Eric S. Raymond
5417 Gilles Vollant
5418
5419and with the following additions to the disclaimer:
5420
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]5421 There is no warranty against interference with your
5422 enjoyment of the library or against infringement.
5423 There is no warranty that our efforts or the library
5424 will fulfill any of your particular purposes or needs.
5425 This library is provided with all faults, and the entire
5426 risk of satisfactory quality, performance, accuracy, and
5427 effort is with the user.
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5428
5429libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
5430Copyright (c) 1998, 1999 Glenn Randers-Pehrson
5431Distributed according to the same disclaimer and license as libpng-0.96,
5432with the following individuals added to the list of Contributing Authors:
5433
5434 Tom Lane
5435 Glenn Randers-Pehrson
5436 Willem van Schaik
5437
5438libpng versions 0.89, June 1996, through 0.96, May 1997, are
Glenn Randers-Pehrson54a066a1999-09-19 06:04:18 -0500[diff] [blame]5439Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5440Distributed according to the same disclaimer and license as libpng-0.88,
5441with the following individuals added to the list of Contributing Authors:
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5442
5443 John Bowler
5444 Kevin Bracey
5445 Sam Bushell
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5446 Magnus Holmgren
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5447 Greg Roelofs
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5448 Tom Tanner
5449
5450libpng versions 0.5, May 1995, through 0.88, January 1996, are
5451Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
5452
5453For the purposes of this copyright and license, "Contributing Authors"
5454is defined as the following set of individuals:
5455
5456 Andreas Dilger
5457 Dave Martindale
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5458 Guy Eric Schalnat
5459 Paul Schmidt
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5460 Tim Wegner
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]5461
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5462The PNG Reference Library is supplied "AS IS". The Contributing Authors
5463and Group 42, Inc. disclaim all warranties, expressed or implied,
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5464including, without limitation, the warranties of merchantability and of
5465fitness for any purpose. The Contributing Authors and Group 42, Inc.
5466assume no liability for direct, indirect, incidental, special, exemplary,
5467or consequential damages, which may result from the use of the PNG
5468Reference Library, even if advised of the possibility of such damage.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]5469
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5470Permission is hereby granted to use, copy, modify, and distribute this
5471source code, or portions hereof, for any purpose, without fee, subject
5472to the following restrictions:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5473
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]54741. The origin of this source code must not be misrepresented.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5475
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]54762. Altered versions must be plainly marked as such and
5477 must not be misrepresented as being the original source.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5478
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]54793. This Copyright notice may not be removed or altered from
5480 any source or altered source distribution.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5481
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5482The Contributing Authors and Group 42, Inc. specifically permit, without
5483fee, and encourage the use of this source code as a component to
5484supporting the PNG file format in commercial products. If you use this
5485source code in a product, acknowledgment is not required but would be
5486appreciated.
5487
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5488
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5489A "png_get_copyright" function is available, for convenient use in "about"
5490boxes and the like:
5491
5492 printf("%s",png_get_copyright(NULL));
5493
5494Also, the PNG logo (in PNG format, of course) is supplied in the
Glenn Randers-Pehrsona4d54bd2000-07-14 08:15:12 -0500[diff] [blame]5495files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]5496
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5497Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]5498certification mark of the Open Source Initiative.
5499
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5500Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]5501glennrp at users.sourceforge.net
Glenn Randers-Pehrson6e418422011-12-29 20:57:39 -0600[diff] [blame^]5502December 30, 2011
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]5503
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]5504.\" end of man page
5505