Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libpng / a7dbcba1e84573b2117a1700cd1336afcbd44360 / . / libpng.3
blob: 29da2b707623b6d5995cecf7a5325e94c2a7f7d1 [file] [log] [blame]
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]1.TH LIBPNG 3 "May 15, 2007"
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]2.SH NAME
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3libpng \- Portable Network Graphics (PNG) Reference Library 1.4.0beta19
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]4.SH SYNOPSIS
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -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-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]12\fBvoid png_chunk_benign_error (png_structp \fP\fIpng_ptr\fP\fB, png_const_charp \fIerror\fP\fB);\fP
13
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]14\fBint png_check_sig (png_bytep \fP\fIsig\fP\fB, int \fInum\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]15
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]16\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]17
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]18\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]19
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]20\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]21
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]22\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]23
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]24\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]25
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]26\fBpng_infop png_create_info_struct (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]27
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]28\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]29
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]30\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
31
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]32\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]33
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]34\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
35
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]36\fBint png_debug(int \fP\fIlevel\fP\fB, png_const_charp \fImessage\fP\fB);\fP
37
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]38\fBint png_debug1(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fIp1\fP\fB);\fP
39
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]40\fBint png_debug2(int \fP\fIlevel\fP\fB, png_const_charp \fP\fImessage\fP\fB, \fP\fIp1\fP\fB, \fIp2\fP\fB);\fP
41
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]42\fBvoid png_destroy_info_struct (png_structp \fP\fIpng_ptr\fP\fB, png_infopp \fIinfo_ptr_ptr\fP\fB);\fP
43
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]44\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
45
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]46\fBvoid png_destroy_write_struct (png_structpp \fP\fIpng_ptr_ptr\fP\fB, png_infopp \fIinfo_ptr_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-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]54\fBvoid png_free_default(png_structp \fP\fIpng_ptr\fP\fB, png_voidp \fIptr\fP\fB);\fP
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
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]58\fBpng_byte png_get_bit_depth (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
59
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]60\fBpng_uint_32 png_get_bKGD (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_16p \fI*background\fP\fB);\fP
61
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]62\fBpng_byte png_get_channels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
63
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]64\fBpng_uint_32 png_get_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fP\fI*white_x\fP\fB, double \fP\fI*white_y\fP\fB, double \fP\fI*red_x\fP\fB, double \fP\fI*red_y\fP\fB, double \fP\fI*green_x\fP\fB, double \fP\fI*green_y\fP\fB, double \fP\fI*blue_x\fP\fB, double \fI*blue_y\fP\fB);\fP
65
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]66\fBpng_uint_32 png_get_cHRM_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*white_x\fP\fB, png_uint_32 \fP\fI*white_y\fP\fB, png_uint_32 \fP\fI*red_x\fP\fB, png_uint_32 \fP\fI*red_y\fP\fB, png_uint_32 \fP\fI*green_x\fP\fB, png_uint_32 \fP\fI*green_y\fP\fB, png_uint_32 \fP\fI*blue_x\fP\fB, png_uint_32 \fI*blue_y\fP\fB);\fP
67
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]68\fBpng_byte png_get_color_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
69
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]70\fBpng_byte png_get_compression_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
71
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]72\fBpng_byte png_get_copyright (png_structp \fIpng_ptr\fP\fB);\fP
73
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]74\fBpng_voidp png_get_error_ptr (png_structp \fIpng_ptr\fP\fB);\fP
75
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]76\fBpng_byte png_get_filter_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
77
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]78\fBpng_uint_32 png_get_gAMA (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, double \fI*file_gamma\fP\fB);\fP
79
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]80\fBpng_uint_32 png_get_gAMA_fixed (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fI*int_file_gamma\fP\fB);\fP
81
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]82\fBpng_byte png_get_header_ver (png_structp \fIpng_ptr\fP\fB);\fP
83
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]84\fBpng_byte png_get_header_version (png_structp \fIpng_ptr\fP\fB);\fP
85
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]86\fBpng_uint_32 png_get_hIST (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_16p \fI*hist\fP\fB);\fP
87
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]88\fBpng_uint_32 png_get_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charpp \fP\fIname\fP\fB, int \fP\fI*compression_type\fP\fB, png_charpp \fP\fIprofile\fP\fB, png_uint_32 \fI*proflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]89
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]90\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
91
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]92\fBpng_uint_32 png_get_image_height (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
93
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]94\fBpng_uint_32 png_get_image_width (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
95
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -0600[diff] [blame]96\fB#if !defined(PNG_1_0_X) png_int_32 png_get_int_32 (png_bytep buf); \fI#endif
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]97
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]98\fBpng_byte png_get_interlace_type (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
99
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]100\fBpng_voidp png_get_io_ptr (png_structp \fIpng_ptr\fP\fB);\fP
101
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]102\fBpng_byte png_get_libpng_ver (png_structp \fIpng_ptr\fP\fB);\fP
103
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]104\fBpng_voidp png_get_mem_ptr(png_structp \fIpng_ptr\fP\fB);\fP
105
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]106\fBpng_uint_32 png_get_oFFs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*offset_x\fP\fB, png_uint_32 \fP\fI*offset_y\fP\fB, int \fI*unit_type\fP\fB);\fP
107
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]108\fBpng_uint_32 png_get_pCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fI*purpose\fP\fB, png_int_32 \fP\fI*X0\fP\fB, png_int_32 \fP\fI*X1\fP\fB, int \fP\fI*type\fP\fB, int \fP\fI*nparams\fP\fB, png_charp \fP\fI*units\fP\fB, png_charpp \fI*params\fP\fB);\fP
109
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]110\fBpng_uint_32 png_get_pHYs (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fP\fI*res_x\fP\fB, png_uint_32 \fP\fI*res_y\fP\fB, int \fI*unit_type\fP\fB);\fP
111
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]112\fBfloat png_get_pixel_aspect_ratio (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
113
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]114\fBpng_uint_32 png_get_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
115
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]116\fBpng_voidp png_get_progressive_ptr (png_structp \fIpng_ptr\fP\fB);\fP
117
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]118\fBpng_uint_32 png_get_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_colorp \fP\fI*palette\fP\fB, int \fI*num_palette\fP\fB);\fP
119
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -0600[diff] [blame]120\fBpng_byte png_get_rgb_to_gray_status (png_structp png_ptr) png_uint_32 png_get_rowbytes (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]121
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]122\fBpng_bytepp png_get_rows (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
123
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]124\fBpng_uint_32 png_get_sBIT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_color_8p \fI*sig_bit\fP\fB);\fP
125
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]126\fBpng_bytep png_get_signature (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
127
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]128\fBpng_uint_32 png_get_sPLT (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_spalette_p \fI*splt_ptr\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]129
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]130\fBpng_uint_32 png_get_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fI*intent\fP\fB);\fP
131
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]132\fBpng_uint_32 png_get_text (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_textp \fP\fI*text_ptr\fP\fB, int \fI*num_text\fP\fB);\fP
133
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]134\fBpng_uint_32 png_get_tIME (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_timep \fI*mod_time\fP\fB);\fP
135
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]136\fBpng_uint_32 png_get_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fI*trans\fP\fB, int \fP\fI*num_trans\fP\fB, png_color_16p \fI*trans_values\fP\fB);\fP
137
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -0600[diff] [blame]138\fB#if !defined(PNG_1_0_X) png_uint_16 png_get_uint_16 (png_bytep \fIbuf\fP\fB);\fP
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]139
140\fBpng_uint_32 png_get_uint_31 (png_bytep \fIbuf\fP\fB);\fP
141
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -0600[diff] [blame]142\fBpng_uint_32 png_get_uint_32 (png_bytep buf); \fI#endif
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]143
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]144\fBpng_uint_32 png_get_unknown_chunks (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_unknown_chunkpp \fIunknowns\fP\fB);\fP
145
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]146\fBpng_voidp png_get_user_chunk_ptr (png_structp \fIpng_ptr\fP\fB);\fP
147
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]148\fBpng_uint_32 png_get_user_height_max( png_structp \fIpng_ptr\fP\fB);\fP
149
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]150\fBpng_voidp png_get_user_transform_ptr (png_structp \fIpng_ptr\fP\fB);\fP
151
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]152\fBpng_uint_32 png_get_user_width_max (png_structp \fIpng_ptr\fP\fB);\fP
153
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]154\fBpng_uint_32 png_get_valid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_uint_32 \fIflag\fP\fB);\fP
155
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]156\fBpng_int_32 png_get_x_offset_microns (png_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
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]158\fBpng_int_32 png_get_x_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]159
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]160\fBpng_uint_32 png_get_x_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
161
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]162\fBpng_int_32 png_get_y_offset_microns (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]163
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]164\fBpng_int_32 png_get_y_offset_pixels (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]165
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]166\fBpng_uint_32 png_get_y_pixels_per_meter (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
167
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]168\fBpng_uint_32 png_get_compression_buffer_size (png_structp \fIpng_ptr\fP\fB);\fP
169
Glenn Randers-Pehrsonc1bfe682002-03-06 22:08:00 -0600[diff] [blame]170\fBint png_handle_as_unknown (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fIchunk_name\fP\fB);\fP
171
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]172\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]173
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]174\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]175
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]176\fBpng_voidp png_malloc_default(png_structp \fP\fIpng_ptr\fP\fB, png_alloc_size_t \fIsize\fP\fB);\fP
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]177
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]178\fBvoidp png_memcpy (png_voidp \fP\fIs1\fP\fB, png_voidp \fP\fIs2\fP\fB, png_size_t \fIsize\fP\fB);\fP
179
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]180\fBvoidp png_memset (png_voidp \fP\fIs1\fP\fB, int \fP\fIvalue\fP\fB, png_size_t \fIsize\fP\fB);\fP
181
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]182\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
183
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]184\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
185
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]186\fBvoid png_read_destroy (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_infop \fIend_info_ptr\fP\fB);\fP
187
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]188\fBvoid png_read_end (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
189
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]190\fBvoid png_read_image (png_structp \fP\fIpng_ptr\fP\fB, png_bytepp \fIimage\fP\fB);\fP
191
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]192\fBvoid png_read_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
193
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]194\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]195
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]196\fBvoid png_read_row (png_structp \fP\fIpng_ptr\fP\fB, png_bytep \fP\fIrow\fP\fB, png_bytep \fIdisplay_row\fP\fB);\fP
197
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]198\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
199
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]200\fBvoid png_read_update_info (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
201
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -0600[diff] [blame]202\fB#if !defined(PNG_1_0_X) png_save_int_32 (png_bytep \fP\fIbuf\fP\fB, png_int_32 \fIi\fP\fB);\fP
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]203
204\fBvoid png_save_uint_16 (png_bytep \fP\fIbuf\fP\fB, unsigned int \fIi\fP\fB);\fP
205
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]206\fBvoid png_save_uint_32 (png_bytep \fP\fIbuf\fP\fB, png_uint_32 \fIi\fP\fB);\fP
207
Glenn Randers-Pehrsonae4bd5c2006-11-16 20:35:49 -0600[diff] [blame]208\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int flags); \fI#endif
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]209
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]210\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
211
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]212\fBvoid png_set_bgr (png_structp \fIpng_ptr\fP\fB);\fP
213
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]214\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
215
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]216\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
217
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]218\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
219
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]220\fBvoid png_set_compression_level (png_structp \fP\fIpng_ptr\fP\fB, int \fIlevel\fP\fB);\fP
221
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]222\fBvoid png_set_compression_mem_level (png_structp \fP\fIpng_ptr\fP\fB, int \fImem_level\fP\fB);\fP
223
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]224\fBvoid png_set_compression_method (png_structp \fP\fIpng_ptr\fP\fB, int \fImethod\fP\fB);\fP
225
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]226\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]227
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]228\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]229
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]230\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]231
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]232\fBvoid png_set_dither (png_structp \fP\fIpng_ptr\fP\fB, png_colorp \fP\fIpalette\fP\fB, int \fP\fInum_palette\fP\fB, int \fP\fImaximum_colors\fP\fB, png_uint_16p \fP\fIhistogram\fP\fB, int \fIfull_dither\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]233
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]234\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]235
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]236\fBvoid png_set_expand (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]237
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]238\fBvoid png_set_expand_gray_1_2_4_to_8(png_structp \fIpng_ptr\fP\fB);\fP
239
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]240\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]241
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]242\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]243
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]244\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]245
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]246\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]247
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]248\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]249
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]250\fBvoid 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-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]251
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]252\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
253
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]254\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]255
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]256\fBvoid png_set_gray_to_rgb (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]257
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]258\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]259
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]260\fBvoid png_set_iCCP (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIname\fP\fB, int \fP\fIcompression_type\fP\fB, png_charp \fP\fIprofile\fP\fB, png_uint_32 \fIproflen\fP\fB);\fP
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]261
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]262\fBint png_set_interlace_handling (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]263
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]264\fBvoid png_set_invalid (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fImask\fP\fB);\fP
265
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]266\fBvoid png_set_invert_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]267
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]268\fBvoid png_set_invert_mono (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]269
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]270\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]271
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]272\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]273
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]274\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]275
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]276\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]277
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]278\fBvoid png_set_packing (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]279
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]280\fBvoid png_set_packswap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]281
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]282\fBvoid png_set_palette_to_rgb(png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]283
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]284\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]285
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]286\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]287
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]288\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]289
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]290\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]291
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]292\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]293
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]294\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]295
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]296\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]297
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]298\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
299
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]300\fBvoid png_set_rgb_to_gray_fixed (png_structp \fP\fIpng_ptr\fP\fB, int error_action png_fixed_point \fP\fIred\fP\fB, png_fixed_point \fIgreen\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]301
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]302\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
303
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]304\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]305
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]306\fBvoid png_set_sCAL (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_charp \fP\fIunit\fP\fB, double \fP\fIwidth\fP\fB, double \fIheight\fP\fB);\fP
307
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]308\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]309
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]310\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]311
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]312\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]313
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]314\fBvoid png_set_sRGB (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]315
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]316\fBvoid png_set_sRGB_gAMA_and_cHRM (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, int \fIintent\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]317
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]318\fBvoid png_set_strip_16 (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]319
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]320\fBvoid png_set_strip_alpha (png_structp \fIpng_ptr\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_swap (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]323
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]324\fBvoid png_set_swap_alpha (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]325
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]326\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]327
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]328\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]329
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]330\fBvoid png_set_tRNS (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fP\fIinfo_ptr\fP\fB, png_bytep \fP\fItrans\fP\fB, int \fP\fInum_trans\fP\fB, png_color_16p \fItrans_values\fP\fB);\fP
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]331
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]332\fBvoid png_set_tRNS_to_alpha(png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]333
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]334\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
335
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]336\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
337
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]338\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
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]339
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]340\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
341
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]342\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]343
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]344\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]345
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]346\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]347
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]348\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]349
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]350\fBvoid png_set_compression_buffer_size(png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fIsize\fP\fB);\fP
351
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]352\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]353
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]354\fBvoid png_start_read_image (png_structp \fIpng_ptr\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_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]357
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]358\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]359
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]360\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]361
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]362\fBvoid png_write_chunk_end (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_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]365
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]366\fBvoid png_write_destroy (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]367
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]368\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]369
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]370\fBvoid png_write_flush (png_structp \fIpng_ptr\fP\fB);\fP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]371
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]372\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]373
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]374\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]375
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]376\fBvoid png_write_info_before_PLTE (png_structp \fP\fIpng_ptr\fP\fB, png_infop \fIinfo_ptr\fP\fB);\fP
377
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]378\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]379
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]380\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]381
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]382\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]383
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]384\fBvoid png_write_sig (png_structp \fIpng_ptr\fP\fB);\fP
385
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]386\fBvoidpf png_zalloc (voidpf \fP\fIpng_ptr\fP\fB, uInt \fP\fIitems\fP\fB, uInt \fIsize\fP\fB);\fP
387
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]388\fBvoid png_zfree (voidpf \fP\fIpng_ptr\fP\fB, voidpf \fIptr\fP\fB);\fP
389
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]390.SH DESCRIPTION
391The
392.I libpng
393library supports encoding, decoding, and various manipulations of
394the Portable Network Graphics (PNG) format image files. It uses the
395.IR zlib(3)
396compression library.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]397Following is a copy of the libpng.txt file that accompanies libpng.
398.SH LIBPNG.TXT
399libpng.txt - A description on how to use and modify libpng
400
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]401 libpng version 1.4.0beta19 - May 15, 2007
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]402 Updated and distributed by Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]403 <glennrp at users.sourceforge.net>
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]404 Copyright (c) 1998-2005 Glenn Randers-Pehrson
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]405 For conditions of distribution and use, see copyright
406 notice in png.h.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]407
408 based on:
409
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]410 libpng 1.0 beta 6 version 0.96 May 28, 1997
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]411 Updated and distributed by Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]412 Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]413
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]414 libpng 1.0 beta 2 - version 0.88 January 26, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]415 For conditions of distribution and use, see copyright
416 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]417 Schalnat, Group 42, Inc.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]418
419 Updated/rewritten per request in the libpng FAQ
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]420 Copyright (c) 1995, 1996 Frank J. T. Wojcik
421 December 18, 1995 & January 20, 1996
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]422
423.SH I. Introduction
424
425This file describes how to use and modify the PNG reference library
426(known as libpng) for your own use. There are five sections to this
427file: introduction, structures, reading, writing, and modification and
428configuration notes for various special platforms. In addition to this
429file, example.c is a good starting point for using the library, as
430it is heavily commented and should include everything most people
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]431will need. We assume that libpng is already installed; see the
432INSTALL file for instructions on how to install libpng.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]433
434Libpng was written as a companion to the PNG specification, as a way
435of reducing the amount of time and effort it takes to support the PNG
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]436file format in application programs.
437
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]438The PNG specification (second edition), November 2003, is available as
439a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
440<http://www.w3.org/TR/2003/REC-PNG-20031110/
441The W3C and ISO documents have identical technical content.
442
443The PNG-1.2 specification is available at
444<http://www.libpng.org/pub/png/documents/>
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]445
446The PNG-1.0 specification is available
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]447as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]448W3C Recommendation <http://www.w3.org/TR/REC.png.html>. Some
449additional chunks are described in the special-purpose public chunks
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]450documents at <http://www.libpng.org/pub/png/documents/>.
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]451
452Other information
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]453about 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]454page, <http://www.libpng.org/pub/png/>.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]455
456Most users will not have to modify the library significantly; advanced
457users may want to modify it more. All attempts were made to make it as
458complete as possible, while keeping the code easy to understand.
459Currently, this library only supports C. Support for other languages
460is being considered.
461
462Libpng has been designed to handle multiple sessions at one time,
463to be easily modifiable, to be portable to the vast majority of
464machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
465to use. The ultimate goal of libpng is to promote the acceptance of
466the PNG file format in whatever way possible. While there is still
467work to be done (see the TODO file), libpng should cover the
468majority of the needs of its users.
469
470Libpng uses zlib for its compression and decompression of PNG files.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]471Further information about zlib, and the latest version of zlib, can
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]472be 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]473The zlib compression utility is a general purpose utility that is
474useful for more than PNG files, and can be used without libpng.
475See the documentation delivered with zlib for more details.
476You can usually find the source files for the zlib utility wherever you
477find the libpng source files.
478
479Libpng is thread safe, provided the threads are using different
480instances of the structures. Each thread should have its own
481png_struct and png_info instances, and thus its own image.
482Libpng does not protect itself against two threads using the
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]483same instance of a structure. Note: thread safety may be defeated
484by use of some of the MMX assembler code in pnggccrd.c, which is only
485compiled when the user defines PNG_THREAD_UNSAFE_OK.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]486
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]487.SH II. Structures
488
489There are two main structures that are important to libpng, png_struct
490and png_info. The first, png_struct, is an internal structure that
491will not, for the most part, be used by a user except as the first
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]492variable passed to every libpng function call.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]493
494The png_info structure is designed to provide information about the
495PNG file. At one time, the fields of png_info were intended to be
496directly accessible to the user. However, this tended to cause problems
497with applications using dynamically loaded libraries, and as a result
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]498a set of interface functions for png_info (the png_get_*() and png_set_*()
499functions) was developed. The fields of png_info are still available for
500older applications, but it is suggested that applications use the new
501interfaces if at all possible.
502
503Applications that do make direct access to the members of png_struct (except
504for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
505and applications that make direct access to the members of png_info must
506be recompiled if they were compiled or loaded with libpng version 1.0.6,
507in which the members were in a different order. In version 1.0.7, the
508members of the png_info structure reverted to the old order, as they were
509in versions 0.97c through 1.0.5. Starting with version 2.0.0, both
510structures are going to be hidden, and the contents of the structures will
511only be accessible through the png_get/png_set functions.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]512
513The png.h header file is an invaluable reference for programming with libpng.
514And while I'm on the topic, make sure you include the libpng header file:
515
516#include <png.h>
517
518.SH III. Reading
519
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]520We'll now walk you through the possible functions to call when reading
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]521in a PNG file sequentially, briefly explaining the syntax and purpose
522of each one. See example.c and png.h for more detail. While
523progressive reading is covered in the next section, you will still
524need some of the functions discussed in this section to read a PNG
525file.
526
527.SS Setup
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]528
529You will want to do the I/O initialization(*) before you get into libpng,
530so if it doesn't work, you don't have much to undo. Of course, you
531will also want to insure that you are, in fact, dealing with a PNG
532file. 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]533To use it, pass in the first 1 to 8 bytes of the file to the function
534png_sig_cmp(), and it will return 0 if the bytes match the corresponding
535bytes of the PNG signature, or nonzero otherwise. Of course, the more bytes
536you pass in, the greater the accuracy of the prediction.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]537
538If you are intending to keep the file pointer open for use in libpng,
539you must ensure you don't read more than 8 bytes from the beginning
540of the file, and you also have to make a call to png_set_sig_bytes_read()
541with the number of bytes you read from the beginning. Libpng will
542then only check the bytes (if any) that your program didn't read.
543
544(*): If you are not using the standard I/O functions, you will need
545to replace them with custom functions. See the discussion under
546Customizing libpng.
547
548
549 FILE *fp = fopen(file_name, "rb");
550 if (!fp)
551 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]552 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]553 }
554 fread(header, 1, number, fp);
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]555 is_png = !png_sig_cmp(header, 0, number);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]556 if (!is_png)
557 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]558 return (NOT_PNG);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]559 }
560
561
562Next, png_struct and png_info need to be allocated and initialized. In
563order to ensure that the size of these structures is correct even with a
564dynamically linked libpng, there are functions to initialize and
565allocate the structures. We also pass the library version, optional
566pointers to error handling functions, and a pointer to a data struct for
567use by the error functions, if necessary (the pointer and functions can
568be NULL if the default error handlers are to be used). See the section
569on Changes to Libpng below regarding the old initialization functions.
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]570The structure allocation functions quietly return NULL if they fail to
571create the structure, so your application should check for that.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]572
573 png_structp png_ptr = png_create_read_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]574 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]575 user_error_fn, user_warning_fn);
576 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]577 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]578
579 png_infop info_ptr = png_create_info_struct(png_ptr);
580 if (!info_ptr)
581 {
582 png_destroy_read_struct(&png_ptr,
583 (png_infopp)NULL, (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]584 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]585 }
586
587 png_infop end_info = png_create_info_struct(png_ptr);
588 if (!end_info)
589 {
590 png_destroy_read_struct(&png_ptr, &info_ptr,
591 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]592 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]593 }
594
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]595If you want to use your own memory allocation routines,
596define PNG_USER_MEM_SUPPORTED and use
597png_create_read_struct_2() instead of png_create_read_struct():
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]598
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]599 png_structp png_ptr = png_create_read_struct_2
600 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
601 user_error_fn, user_warning_fn, (png_voidp)
602 user_mem_ptr, user_malloc_fn, user_free_fn);
603
604The error handling routines passed to png_create_read_struct()
605and the memory alloc/free routines passed to png_create_struct_2()
606are only necessary if you are not using the libpng supplied error
607handling and memory alloc/free functions.
608
609When libpng encounters an error, it expects to longjmp back
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]610to your routine. Therefore, you will need to call setjmp and pass
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]611your png_jmpbuf(png_ptr). If you read the file from different
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]612routines, you will need to update the jmpbuf field every time you enter
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]613a new routine that will call a png_*() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]614
615See your documentation of setjmp/longjmp for your compiler for more
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]616information on setjmp/longjmp. See the discussion on libpng error
617handling in the Customizing Libpng section below for more information
618on the libpng error handling. If an error occurs, and libpng longjmp's
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]619back to your setjmp, you will want to call png_destroy_read_struct() to
620free any memory.
621
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]622 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]623 {
624 png_destroy_read_struct(&png_ptr, &info_ptr,
625 &end_info);
626 fclose(fp);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]627 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]628 }
629
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]630If you would rather avoid the complexity of setjmp/longjmp issues,
631you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
632errors will result in a call to PNG_ABORT() which defaults to abort().
633
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]634Now you need to set up the input code. The default for libpng is to
635use the C function fread(). If you use this, you will need to pass a
636valid FILE * in the function png_init_io(). Be sure that the file is
637opened in binary mode. If you wish to handle reading data in another
638way, you need not call the png_init_io() function, but you must then
639implement the libpng I/O methods discussed in the Customizing Libpng
640section below.
641
642 png_init_io(png_ptr, fp);
643
644If you had previously opened the file and read any of the signature from
645the beginning in order to see if this was a PNG file, you need to let
646libpng know that there are some bytes missing from the start of the file.
647
648 png_set_sig_bytes(png_ptr, number);
649
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]650.SS Setting up callback code
651
652You can set up a callback function to handle any unknown chunks in the
653input stream. You must supply the function
654
655 read_chunk_callback(png_ptr ptr,
656 png_unknown_chunkp chunk);
657 {
658 /* The unknown chunk structure contains your
659 chunk data: */
660 png_byte name[5];
661 png_byte *data;
662 png_size_t size;
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]663 /* Note that libpng has already taken care of
664 the CRC handling */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]665
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]666 /* put your code here. Return one of the
667 following: */
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]668
669 return (-n); /* chunk had an error */
670 return (0); /* did not recognize */
671 return (n); /* success */
672 }
673
674(You can give your function another name that you like instead of
675"read_chunk_callback")
676
677To inform libpng about your function, use
678
679 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
680 read_chunk_callback);
681
682This names not only the callback function, but also a user pointer that
683you can retrieve with
684
685 png_get_user_chunk_ptr(png_ptr);
686
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]687At this point, you can set up a callback function that will be
688called after each row has been read, which you can use to control
689a progress meter or the like. It's demonstrated in pngtest.c.
690You must supply a function
691
Glenn Randers-Pehrsone68f5a32001-05-14 09:20:53 -0500[diff] [blame]692 void read_row_callback(png_ptr ptr, png_uint_32 row,
693 int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]694 {
695 /* put your code here */
696 }
697
698(You can give it another name that you like instead of "read_row_callback")
699
700To inform libpng about your function, use
701
702 png_set_read_status_fn(png_ptr, read_row_callback);
703
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]704.SS Width and height limits
705
706The PNG specification allows the width and height of an image to be as
707large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
708Since very few applications really need to process such large images,
709we have imposed an arbitrary 1-million limit on rows and columns.
710Larger images will be rejected immediately with a png_error() call. If
711you wish to override this limit, you can use
712
713 png_set_user_limits(png_ptr, width_max, height_max);
714
715to set your own limits, or use width_max = height_max = 0x7fffffffL
716to allow all valid dimensions (libpng may reject some very large images
717anyway because of potential buffer overflow conditions).
718
719You should put this statement after you create the PNG structure and
720before calling png_read_info(), png_read_png(), or png_process_data().
721If you need to retrieve the limits that are being applied, use
722
723 width_max = png_get_user_width_max(png_ptr);
724 height_max = png_get_user_height_max(png_ptr);
725
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]726.SS Unknown-chunk handling
727
728Now you get to set the way the library processes unknown chunks in the
729input PNG stream. Both known and unknown chunks will be read. Normal
730behavior is that known chunks will be parsed into information in
731various info_ptr members; unknown chunks will be discarded. To change
732this, you can call:
733
Glenn Randers-Pehrson272489d2004-08-04 06:34:52 -0500[diff] [blame]734 png_set_keep_unknown_chunks(png_ptr, keep,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]735 chunk_list, num_chunks);
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]736 keep - 0: do not handle as unknown
737 1: do not keep
738 2: keep only if safe-to-copy
739 3: keep even if unsafe-to-copy
740 You can use these definitions:
741 PNG_HANDLE_CHUNK_AS_DEFAULT 0
742 PNG_HANDLE_CHUNK_NEVER 1
743 PNG_HANDLE_CHUNK_IF_SAFE 2
744 PNG_HANDLE_CHUNK_ALWAYS 3
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]745 chunk_list - list of chunks affected (a byte string,
746 five bytes per chunk, NULL or '\0' if
747 num_chunks is 0)
748 num_chunks - number of chunks affected; if 0, all
Glenn Randers-Pehrsondff799e2004-08-07 21:42:49 -0500[diff] [blame]749 unknown chunks are affected. If nonzero,
750 only the chunks in the list are affected
751
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]752Unknown chunks declared in this way will be saved as raw data onto a
753list of png_unknown_chunk structures. If a chunk that is normally
754known to libpng is named in the list, it will be handled as unknown,
755according to the "keep" directive. If a chunk is named in successive
756instances of png_set_keep_unknown_chunks(), the final instance will
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]757take precedence. The IHDR and IEND chunks should not be named in
758chunk_list; if they are, libpng will process them normally anyway.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]759
760.SS The high-level read interface
761
762At this point there are two ways to proceed; through the high-level
763read interface, or through a sequence of low-level read operations.
764You can use the high-level interface if (a) you are willing to read
765the entire image into memory, and (b) the input transformations
766you want to do are limited to the following set:
767
768 PNG_TRANSFORM_IDENTITY No transformation
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]769 PNG_TRANSFORM_STRIP_16 Strip 16-bit samples to
770 8 bits
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]771 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]772 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
773 samples to bytes
774 PNG_TRANSFORM_PACKSWAP Change order of packed
775 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]776 PNG_TRANSFORM_EXPAND Perform set_expand()
777 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]778 PNG_TRANSFORM_SHIFT Normalize pixels to the
779 sBIT depth
780 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
781 to BGRA
782 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
783 to AG
784 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
785 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]786 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
787
788(This excludes setting a background color, doing gamma transformation,
789dithering, and setting filler.) If this is the case, simply do this:
790
791 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
792
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]793where png_transforms is an integer containing the bitwise OR of
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]794some set of transformation flags. This call is equivalent to png_read_info(),
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]795followed the set of transformations indicated by the transform mask,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]796then png_read_image(), and finally png_read_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]797
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]798(The final parameter of this call is not yet used. Someday it might point
799to transformation parameters required by some future input transform.)
800
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]801You must use png_transforms and not call any png_set_transform() functions
802when you use png_read_png().
803
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]804After you have called png_read_png(), you can retrieve the image data
805with
806
807 row_pointers = png_get_rows(png_ptr, info_ptr);
808
809where row_pointers is an array of pointers to the pixel data for each row:
810
811 png_bytep row_pointers[height];
812
813If you know your image size and pixel size ahead of time, you can allocate
814row_pointers prior to calling png_read_png() with
815
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]816 if (height > PNG_UINT_32_MAX/sizeof(png_bytep))
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]817 png_error (png_ptr,
818 "Image is too tall to process in memory");
819 if (width > PNG_UINT_32_MAX/pixel_size)
820 png_error (png_ptr,
821 "Image is too wide to process in memory");
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]822 row_pointers = png_malloc(png_ptr,
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]823 height*sizeof(png_bytep));
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]824 for (int i=0; i<height, i++)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]825 row_pointers[i]=png_malloc(png_ptr,
826 width*pixel_size);
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]827 png_set_rows(png_ptr, info_ptr, &row_pointers);
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]828
829Alternatively you could allocate your image in one big block and define
830row_pointers[i] to point into the proper places in your block.
831
832If you use png_set_rows(), the application is responsible for freeing
833row_pointers (and row_pointers[i], if they were separately allocated).
834
835If you don't allocate row_pointers ahead of time, png_read_png() will
836do it, and it'll be free'ed when you call png_destroy_*().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]837
838.SS The low-level read interface
839
840If you are going the low-level route, you are now ready to read all
841the file information up to the actual image data. You do this with a
842call to png_read_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]843
844 png_read_info(png_ptr, info_ptr);
845
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]846This will process all chunks up to but not including the image data.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]847
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]848.SS Querying the info structure
849
850Functions are used to get the information from the info_ptr once it
851has been read. Note that these fields may not be completely filled
852in until png_read_end() has read the chunk data following the image.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]853
854 png_get_IHDR(png_ptr, info_ptr, &width, &height,
855 &bit_depth, &color_type, &interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]856 &compression_type, &filter_method);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]857
858 width - holds the width of the image
859 in pixels (up to 2^31).
860 height - holds the height of the image
861 in pixels (up to 2^31).
862 bit_depth - holds the bit depth of one of the
863 image channels. (valid values are
864 1, 2, 4, 8, 16 and depend also on
865 the color_type. See also
866 significant bits (sBIT) below).
867 color_type - describes which color/alpha channels
868 are present.
869 PNG_COLOR_TYPE_GRAY
870 (bit depths 1, 2, 4, 8, 16)
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]871 PNG_COLOR_TYPE_GRAY_ALPHA
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]872 (bit depths 8, 16)
873 PNG_COLOR_TYPE_PALETTE
874 (bit depths 1, 2, 4, 8)
875 PNG_COLOR_TYPE_RGB
876 (bit_depths 8, 16)
877 PNG_COLOR_TYPE_RGB_ALPHA
878 (bit_depths 8, 16)
879
880 PNG_COLOR_MASK_PALETTE
881 PNG_COLOR_MASK_COLOR
882 PNG_COLOR_MASK_ALPHA
883
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]884 filter_method - (must be PNG_FILTER_TYPE_BASE
885 for PNG 1.0, and can also be
886 PNG_INTRAPIXEL_DIFFERENCING if
887 the PNG datastream is embedded in
888 a MNG-1.0 datastream)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]889 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
890 for PNG 1.0)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]891 interlace_type - (PNG_INTERLACE_NONE or
892 PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]893 Any or all of interlace_type, compression_type, of
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]894 filter_method can be NULL if you are
895 not interested in their values.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]896
897 channels = png_get_channels(png_ptr, info_ptr);
898 channels - number of channels of info for the
899 color type (valid values are 1 (GRAY,
900 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
901 4 (RGB_ALPHA or RGB + filler byte))
902 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
903 rowbytes - number of bytes needed to hold a row
904
905 signature = png_get_signature(png_ptr, info_ptr);
906 signature - holds the signature read from the
907 file (if any). The data is kept in
908 the same offset it would be if the
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]909 whole signature were read (i.e. if an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]910 application had already read in 4
911 bytes of signature before starting
912 libpng, the remaining 4 bytes would
913 be in signature[4] through signature[7]
914 (see png_set_sig_bytes())).
915
916
917 width = png_get_image_width(png_ptr,
918 info_ptr);
919 height = png_get_image_height(png_ptr,
920 info_ptr);
921 bit_depth = png_get_bit_depth(png_ptr,
922 info_ptr);
923 color_type = png_get_color_type(png_ptr,
924 info_ptr);
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]925 filter_method = png_get_filter_type(png_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]926 info_ptr);
927 compression_type = png_get_compression_type(png_ptr,
928 info_ptr);
929 interlace_type = png_get_interlace_type(png_ptr,
930 info_ptr);
931
932
933These are also important, but their validity depends on whether the chunk
934has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
935png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
936data has been read, or zero if it is missing. The parameters to the
937png_get_<chunk> are set directly if they are simple data types, or a pointer
938into the info_ptr is returned for any complex types.
939
940 png_get_PLTE(png_ptr, info_ptr, &palette,
941 &num_palette);
942 palette - the palette for the file
943 (array of png_color)
944 num_palette - number of entries in the palette
945
946 png_get_gAMA(png_ptr, info_ptr, &gamma);
947 gamma - the gamma the file is written
948 at (PNG_INFO_gAMA)
949
950 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
951 srgb_intent - the rendering intent (PNG_INFO_sRGB)
952 The presence of the sRGB chunk
953 means that the pixel data is in the
954 sRGB color space. This chunk also
955 implies specific values of gAMA and
956 cHRM.
957
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]958 png_get_iCCP(png_ptr, info_ptr, &name,
959 &compression_type, &profile, &proflen);
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]960 name - The profile name.
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]961 compression - The compression type; always
962 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
963 You may give NULL to this argument to
964 ignore it.
965 profile - International Color Consortium color
966 profile data. May contain NULs.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]967 proflen - length of profile data in bytes.
968
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]969 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
970 sig_bit - the number of significant bits for
971 (PNG_INFO_sBIT) each of the gray,
972 red, green, and blue channels,
973 whichever are appropriate for the
974 given color type (png_color_16)
975
976 png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
977 &trans_values);
978 trans - array of transparent entries for
979 palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]980 trans_values - graylevel or color sample values of
981 the single transparent color for
982 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]983 num_trans - number of transparent entries
984 (PNG_INFO_tRNS)
985
986 png_get_hIST(png_ptr, info_ptr, &hist);
987 (PNG_INFO_hIST)
988 hist - histogram of palette (array of
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]989 png_uint_16)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]990
991 png_get_tIME(png_ptr, info_ptr, &mod_time);
992 mod_time - time image was last modified
993 (PNG_VALID_tIME)
994
995 png_get_bKGD(png_ptr, info_ptr, &background);
996 background - background color (PNG_VALID_bKGD)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]997 valid 16-bit red, green and blue
998 values, regardless of color_type
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]999
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1000 num_comments = png_get_text(png_ptr, info_ptr,
1001 &text_ptr, &num_text);
1002 num_comments - number of comments
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1003 text_ptr - array of png_text holding image
1004 comments
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1005 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1006 on "text" PNG_TEXT_COMPRESSION_NONE
1007 PNG_TEXT_COMPRESSION_zTXt
1008 PNG_ITXT_COMPRESSION_NONE
1009 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1010 text_ptr[i].key - keyword for comment. Must contain
1011 1-79 characters.
1012 text_ptr[i].text - text comments for current
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1013 keyword. Can be empty.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1014 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1015 after decompression, 0 for iTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1016 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1017 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1018 text_ptr[i].lang - language of comment (empty
1019 string for unknown).
Glenn Randers-Pehrson73d57cb2002-03-25 18:49:08 -0600[diff] [blame]1020 text_ptr[i].lang_key - keyword in UTF-8
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1021 (empty string for unknown).
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1022 num_text - number of comments (same as
1023 num_comments; you can put NULL here
1024 to avoid the duplication)
1025 Note while png_set_text() will accept text, language,
1026 and translated keywords that can be NULL pointers, the
1027 structure returned by png_get_text will always contain
1028 regular zero-terminated C strings. They might be
1029 empty strings but they will never be NULL pointers.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1030
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1031 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1032 &palette_ptr);
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1033 palette_ptr - array of palette structures holding
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1034 contents of one or more sPLT chunks
1035 read.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1036 num_spalettes - number of sPLT chunks read.
1037
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1038 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1039 &unit_type);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1040 offset_x - positive offset from the left edge
1041 of the screen
1042 offset_y - positive offset from the top edge
1043 of the screen
1044 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1045
1046 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1047 &unit_type);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1048 res_x - pixels/unit physical resolution in
1049 x direction
1050 res_y - pixels/unit physical resolution in
1051 x direction
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1052 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1053 PNG_RESOLUTION_METER
1054
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1055 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1056 &height)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1057 unit - physical scale units (an integer)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1058 width - width of a pixel in physical scale units
1059 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1060 (width and height are doubles)
1061
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1062 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1063 &height)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1064 unit - physical scale units (an integer)
1065 width - width of a pixel in physical scale units
1066 height - height of a pixel in physical scale units
1067 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1068
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1069 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1070 info_ptr, &unknowns)
1071 unknowns - array of png_unknown_chunk
1072 structures holding unknown chunks
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1073 unknowns[i].name - name of unknown chunk
1074 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1075 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1076 unknowns[i].location - position of chunk in file
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1077
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1078 The value of "i" corresponds to the order in which the
1079 chunks were read from the PNG file or inserted with the
1080 png_set_unknown_chunks() function.
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1081
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1082The data from the pHYs chunk can be retrieved in several convenient
1083forms:
1084
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1085 res_x = png_get_x_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1086 info_ptr)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1087 res_y = png_get_y_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1088 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1089 res_x_and_y = png_get_pixels_per_meter(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1090 info_ptr)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1091 res_x = png_get_x_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1092 info_ptr)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1093 res_y = png_get_y_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1094 info_ptr)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1095 res_x_and_y = png_get_pixels_per_inch(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1096 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1097 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1098 info_ptr)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1099
1100 (Each of these returns 0 [signifying "unknown"] if
1101 the data is not present or if res_x is 0;
1102 res_x_and_y is 0 if res_x != res_y)
1103
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1104The data from the oFFs chunk can be retrieved in several convenient
1105forms:
1106
1107 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1108 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1109 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1110 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1111
1112 (Each of these returns 0 [signifying "unknown" if both
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1113 x and y are 0] if the data is not present or if the
1114 chunk is present but the unit is the pixel)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1115
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1116For more information, see the png_info definition in png.h and the
1117PNG specification for chunk contents. Be careful with trusting
1118rowbytes, as some of the transformations could increase the space
1119needed to hold a row (expand, filler, gray_to_rgb, etc.).
1120See png_read_update_info(), below.
1121
1122A quick word about text_ptr and num_text. PNG stores comments in
1123keyword/text pairs, one pair per chunk, with no limit on the number
1124of text chunks, and a 2^31 byte limit on their size. While there are
1125suggested keywords, there is no requirement to restrict the use to these
1126strings. It is strongly suggested that keywords and text be sensible
1127to humans (that's the point), so don't use abbreviations. Non-printing
1128symbols are not allowed. See the PNG specification for more details.
1129There is also no requirement to have text after the keyword.
1130
1131Keywords should be limited to 79 Latin-1 characters without leading or
1132trailing spaces, but non-consecutive spaces are allowed within the
1133keyword. It is possible to have the same keyword any number of times.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1134The text_ptr is an array of png_text structures, each holding a
1135pointer to a language string, a pointer to a keyword and a pointer to
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1136a text string. The text string, language code, and translated
1137keyword may be empty or NULL pointers. The keyword/text
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1138pairs are put into the array in the order that they are received.
1139However, some or all of the text chunks may be after the image, so, to
1140make sure you have read all the text chunks, don't mess with these
1141until after you read the stuff after the image. This will be
1142mentioned again below in the discussion that goes with png_read_end().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1143
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1144.SS Input transformations
1145
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1146After you've read the header information, you can set up the library
1147to handle any special transformations of the image data. The various
1148ways to transform the data will be described in the order that they
1149should occur. This is important, as some of these change the color
1150type and/or bit depth of the data, and some others only work on
1151certain color types and bit depths. Even though each transformation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1152checks 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]1153make sure to only enable a transformation if it will be valid for the
1154data. For example, don't swap red and blue on grayscale data.
1155
1156The colors used for the background and transparency values should be
1157supplied in the same format/depth as the current image data. They
1158are stored in the same format/depth as the image data in a bKGD or tRNS
1159chunk, so this is what libpng expects for this data. The colors are
1160transformed to keep in sync with the image data when an application
1161calls the png_read_update_info() routine (see below).
1162
1163Data will be decoded into the supplied row buffers packed into bytes
1164unless the library has been told to transform it into another format.
1165For example, 4 bit/pixel paletted or grayscale data will be returned
11662 pixels/byte with the leftmost pixel in the high-order bits of the
1167byte, unless png_set_packing() is called. 8-bit RGB data will be stored
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1168in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
1169is called to insert filler bytes, either before or after each RGB triplet.
117016-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
1171byte of the color value first, unless png_set_strip_16() is called to
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]1172transform it to regular RGB RGB triplets, or png_set_filler() or
1173png_set_add alpha() is called to insert filler bytes, either before or
1174after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
1175be modified with
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1176png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1177
1178The following code transforms grayscale images of less than 8 to 8 bits,
1179changes paletted images to RGB, and adds a full alpha channel if there is
1180transparency information in a tRNS chunk. This is most useful on
1181grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1182viewing application that wishes to treat all images in the same way.
1183
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1184 if (color_type == PNG_COLOR_TYPE_PALETTE)
1185 png_set_palette_to_rgb(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1186
1187 if (color_type == PNG_COLOR_TYPE_GRAY &&
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]1188 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1189
1190 if (png_get_valid(png_ptr, info_ptr,
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1191 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1192
1193These three functions are actually aliases for png_set_expand(), added
1194in libpng version 1.0.4, with the function names expanded to improve code
1195readability. In some future version they may actually do different
1196things.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1197
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]1198As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
1199added. It expands the sample depth without changing tRNS to alpha.
Glenn Randers-Pehrson1ce08362006-03-08 23:35:59 -0600[diff] [blame]1200
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1201PNG can have files with 16 bits per channel. If you only can handle
12028 bits per channel, this will strip the pixels down to 8 bit.
1203
1204 if (bit_depth == 16)
1205 png_set_strip_16(png_ptr);
1206
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1207If, for some reason, you don't need the alpha channel on an image,
1208and you want to remove it rather than combining it with the background
1209(but the image author certainly had in mind that you *would* combine
1210it with the background, so that's what you should probably do):
1211
1212 if (color_type & PNG_COLOR_MASK_ALPHA)
1213 png_set_strip_alpha(png_ptr);
1214
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1215In PNG files, the alpha channel in an image
1216is the level of opacity. If you need the alpha channel in an image to
1217be the level of transparency instead of opacity, you can invert the
1218alpha channel (or the tRNS chunk data) after it's read, so that 0 is
1219fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
1220images) is fully transparent, with
1221
1222 png_set_invert_alpha(png_ptr);
1223
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1224PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1225they can, resulting in, for example, 8 pixels per byte for 1 bit
1226files. This code expands to 1 pixel per byte without changing the
1227values of the pixels:
1228
1229 if (bit_depth < 8)
1230 png_set_packing(png_ptr);
1231
1232PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1233stored in a PNG image have been "scaled" or "shifted" up to the next
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1234higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] to
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]12358 bits/sample in the range [0, 255]). However, it is also possible to
1236convert the PNG pixel data back to the original bit depth of the image.
1237This call reduces the pixels back down to the original bit depth:
1238
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]1239 png_color_8p sig_bit;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1240
1241 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1242 png_set_shift(png_ptr, sig_bit);
1243
1244PNG files store 3-color pixels in red, green, blue order. This code
1245changes the storage of the pixels to blue, green, red:
1246
1247 if (color_type == PNG_COLOR_TYPE_RGB ||
1248 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1249 png_set_bgr(png_ptr);
1250
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]1251PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
1252into 4 or 8 bytes for windowing systems that need them in this format:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1253
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]1254 if (color_type == PNG_COLOR_TYPE_RGB)
1255 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1256
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]1257where "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]1258either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1259you want the filler before the RGB or after. This transformation
Glenn Randers-Pehrson1b8e5672001-08-25 06:46:06 -0500[diff] [blame]1260does not affect images that already have full alpha channels. To add an
1261opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
1262will generate RGBA pixels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1263
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1264Note that png_set_filler() does not change the color type. If you want
1265to do that, you can add a true alpha channel with
1266
1267 if (color_type == PNG_COLOR_TYPE_RGB ||
1268 color_type == PNG_COLOR_TYPE_GRAY)
1269 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1270
1271where "filler" contains the alpha value to assign to each pixel.
Glenn Randers-Pehrson16e11662004-11-01 14:13:40 -0600[diff] [blame]1272This function was added in libpng-1.2.7.
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]1273
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1274If you are reading an image with an alpha channel, and you need the
1275data as ARGB instead of the normal PNG format RGBA:
1276
1277 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1278 png_set_swap_alpha(png_ptr);
1279
1280For some uses, you may want a grayscale image to be represented as
1281RGB. This code will do that conversion:
1282
1283 if (color_type == PNG_COLOR_TYPE_GRAY ||
1284 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1285 png_set_gray_to_rgb(png_ptr);
1286
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1287Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1288with alpha.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1289
1290 if (color_type == PNG_COLOR_TYPE_RGB ||
1291 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1292 png_set_rgb_to_gray_fixed(png_ptr, error_action,
1293 int red_weight, int green_weight);
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1294
1295 error_action = 1: silently do the conversion
1296 error_action = 2: issue a warning if the original
1297 image has any pixel where
1298 red != green or red != blue
1299 error_action = 3: issue an error and abort the
1300 conversion if the original
1301 image has any pixel where
1302 red != green or red != blue
1303
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1304 red_weight: weight of red component times 100000
1305 green_weight: weight of green component times 100000
1306 If either weight is negative, default
1307 weights (21268, 71514) are used.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1308
1309If you have set error_action = 1 or 2, you can
1310later check whether the image really was gray, after processing
1311the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1312It will return a png_byte that is zero if the image was gray or
13131 if there were any non-gray pixels. bKGD and sBIT data
1314will be silently converted to grayscale, using the green channel
1315data, regardless of the error_action setting.
1316
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1317With red_weight+green_weight<=100000,
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1318the normalized graylevel is computed:
1319
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1320 int rw = red_weight * 65536;
1321 int gw = green_weight * 65536;
1322 int bw = 65536 - (rw + gw);
1323 gray = (rw*red + gw*green + bw*blue)/65536;
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1324
1325The default values approximate those recommended in the Charles
1326Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]1327Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1328
1329 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1330
1331Libpng approximates this with
1332
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1333 Y = 0.21268 * R + 0.7151 * G + 0.07217 * B
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1334
1335which can be expressed with integers as
1336
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1337 Y = (6969 * R + 23434 * G + 2365 * B)/32768
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1338
1339The calculation is done in a linear colorspace, if the image gamma
1340is known.
1341
Glenn Randers-Pehrson73d57cb2002-03-25 18:49:08 -0600[diff] [blame]1342If you have a grayscale and you are using png_set_expand_depth(),
1343png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]1344a higher bit-depth, you must either supply the background color as a gray
1345value at the original file bit-depth (need_expand = 1) or else supply the
1346background color as an RGB triplet at the final, expanded bit depth
1347(need_expand = 0). Similarly, if you are reading a paletted image, you
1348must either supply the background color as a palette index (need_expand = 1)
1349or as an RGB triplet that may or may not be in the palette (need_expand = 0).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1350
1351 png_color_16 my_background;
1352 png_color_16p image_background;
1353
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]1354 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1355 png_set_background(png_ptr, image_background,
1356 PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1357 else
1358 png_set_background(png_ptr, &my_background,
1359 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
1360
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1361The png_set_background() function tells libpng to composite images
1362with alpha or simple transparency against the supplied background
1363color. If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1364you may use this color, or supply another color more suitable for
1365the current display (e.g., the background color from a web page). You
1366need to tell libpng whether the color is in the gamma space of the
1367display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
1368(PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
1369that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
1370know why anyone would use this, but it's here).
1371
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1372To properly display PNG images on any kind of system, the application needs
1373to know what the display gamma is. Ideally, the user will know this, and
1374the application will allow them to set it. One method of allowing the user
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]1375to set the display gamma separately for each system is to check for a
1376SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
1377correctly set.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1378
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]1379Note that display_gamma is the overall gamma correction required to produce
1380pleasing results, which depends on the lighting conditions in the surrounding
1381environment. In a dim or brightly lit room, no compensation other than
1382the physical gamma exponent of the monitor is needed, while in a dark room
1383a slightly smaller exponent is better.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1384
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1385 double gamma, screen_gamma;
1386
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1387 if (/* We have a user-defined screen
1388 gamma value */)
1389 {
1390 screen_gamma = user_defined_screen_gamma;
1391 }
1392 /* One way that applications can share the same
1393 screen gamma value */
1394 else if ((gamma_str = getenv("SCREEN_GAMMA"))
1395 != NULL)
1396 {
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]1397 screen_gamma = (double)atof(gamma_str);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1398 }
1399 /* If we don't have another value */
1400 else
1401 {
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1402 screen_gamma = 2.2; /* A good guess for a
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1403 PC monitor in a bright office or a dim room */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1404 screen_gamma = 2.0; /* A good guess for a
1405 PC monitor in a dark room */
1406 screen_gamma = 1.7 or 1.0; /* A good
1407 guess for Mac systems */
1408 }
1409
1410The png_set_gamma() function handles gamma transformations of the data.
1411Pass both the file gamma and the current screen_gamma. If the file does
1412not have a gamma value, you can pass one anyway if you have an idea what
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1413it is (usually 0.45455 is a good guess for GIF images on PCs). Note
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1414that file gammas are inverted from screen gammas. See the discussions
1415on gamma in the PNG specification for an excellent description of what
1416gamma is, and why all applications should support it. It is strongly
1417recommended that PNG viewers support gamma correction.
1418
1419 if (png_get_gAMA(png_ptr, info_ptr, &gamma))
1420 png_set_gamma(png_ptr, screen_gamma, gamma);
1421 else
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1422 png_set_gamma(png_ptr, screen_gamma, 0.45455);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1423
1424If you need to reduce an RGB file to a paletted file, or if a paletted
1425file has more entries then will fit on your screen, png_set_dither()
1426will do that. Note that this is a simple match dither that merely
1427finds the closest color available. This should work fairly well with
1428optimized palettes, and fairly badly with linear color cubes. If you
1429pass a palette that is larger then maximum_colors, the file will
1430reduce the number of colors in the palette so it will fit into
1431maximum_colors. If there is a histogram, it will use it to make
1432more intelligent choices when reducing the palette. If there is no
1433histogram, it may not do as good a job.
1434
1435 if (color_type & PNG_COLOR_MASK_COLOR)
1436 {
1437 if (png_get_valid(png_ptr, info_ptr,
1438 PNG_INFO_PLTE))
1439 {
Glenn Randers-Pehrson865f4f02002-09-15 20:30:38 -0500[diff] [blame]1440 png_uint_16p histogram = NULL;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1441
1442 png_get_hIST(png_ptr, info_ptr,
1443 &histogram);
1444 png_set_dither(png_ptr, palette, num_palette,
1445 max_screen_colors, histogram, 1);
1446 }
1447 else
1448 {
1449 png_color std_color_cube[MAX_SCREEN_COLORS] =
1450 { ... colors ... };
1451
1452 png_set_dither(png_ptr, std_color_cube,
1453 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1454 NULL,0);
1455 }
1456 }
1457
1458PNG files describe monochrome as black being zero and white being one.
1459The following code will reverse this (make black be one and white be
1460zero):
1461
Glenn Randers-Pehrson1ea0ff32001-08-07 22:25:59 -0500[diff] [blame]1462 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1463 png_set_invert_mono(png_ptr);
1464
1465This function can also be used to invert grayscale and gray-alpha images:
1466
1467 if (color_type == PNG_COLOR_TYPE_GRAY ||
1468 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1469 png_set_invert_mono(png_ptr);
1470
1471PNG files store 16 bit pixels in network byte order (big-endian,
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1472ie. most significant bits first). This code changes the storage to the
1473other way (little-endian, i.e. least significant bits first, the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1474way PCs store them):
1475
1476 if (bit_depth == 16)
1477 png_set_swap(png_ptr);
1478
1479If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1480need to change the order the pixels are packed into bytes, you can use:
1481
1482 if (bit_depth < 8)
1483 png_set_packswap(png_ptr);
1484
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1485Finally, you can write your own transformation function if none of
1486the existing ones meets your needs. This is done by setting a callback
1487with
1488
1489 png_set_read_user_transform_fn(png_ptr,
1490 read_transform_fn);
1491
1492You must supply the function
1493
1494 void read_transform_fn(png_ptr ptr, row_info_ptr
1495 row_info, png_bytep data)
1496
1497See pngtest.c for a working example. Your function will be called
1498after all of the other transformations have been processed.
1499
1500You can also set up a pointer to a user structure for use by your
1501callback function, and you can inform libpng that your transform
1502function will change the number of channels or bit depth with the
1503function
1504
1505 png_set_user_transform_info(png_ptr, user_ptr,
1506 user_depth, user_channels);
1507
1508The user's application, not libpng, is responsible for allocating and
1509freeing any memory required for the user structure.
1510
1511You can retrieve the pointer via the function
1512png_get_user_transform_ptr(). For example:
1513
1514 voidp read_user_transform_ptr =
1515 png_get_user_transform_ptr(png_ptr);
1516
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1517The last thing to handle is interlacing; this is covered in detail below,
1518but you must call the function here if you want libpng to handle expansion
1519of the interlaced image.
1520
1521 number_of_passes = png_set_interlace_handling(png_ptr);
1522
1523After setting the transformations, libpng can update your png_info
1524structure to reflect any transformations you've requested with this
1525call. This is most useful to update the info structure's rowbytes
1526field so you can use it to allocate your image memory. This function
1527will also update your palette with the correct screen_gamma and
1528background if these have been given with the calls above.
1529
1530 png_read_update_info(png_ptr, info_ptr);
1531
1532After you call png_read_update_info(), you can allocate any
1533memory you need to hold the image. The row data is simply
1534raw byte data for all forms of images. As the actual allocation
1535varies among applications, no example will be given. If you
1536are allocating one large chunk, you will need to build an
1537array of pointers to each row, as it will be needed for some
1538of the functions below.
1539
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1540.SS Reading image data
1541
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1542After you've allocated memory, you can read the image data.
1543The simplest way to do this is in one function call. If you are
1544allocating enough memory to hold the whole image, you can just
1545call png_read_image() and libpng will read in all the image data
1546and put it in the memory area supplied. You will need to pass in
1547an array of pointers to each row.
1548
1549This function automatically handles interlacing, so you don't need
1550to call png_set_interlace_handling() or call this function multiple
1551times, or any of that other stuff necessary with png_read_rows().
1552
1553 png_read_image(png_ptr, row_pointers);
1554
1555where row_pointers is:
1556
1557 png_bytep row_pointers[height];
1558
1559You can point to void or char or whatever you use for pixels.
1560
1561If you don't want to read in the whole image at once, you can
1562use png_read_rows() instead. If there is no interlacing (check
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1563interlace_type == PNG_INTERLACE_NONE), this is simple:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1564
1565 png_read_rows(png_ptr, row_pointers, NULL,
1566 number_of_rows);
1567
1568where row_pointers is the same as in the png_read_image() call.
1569
1570If 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]1571a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1572
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1573 png_bytep row_pointer = row;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]1574 png_read_row(png_ptr, row_pointer, NULL);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1575
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1576If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1577get somewhat harder. The only current (PNG Specification version 1.2)
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1578interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1579is a somewhat complicated 2D interlace scheme, known as Adam7, that
1580breaks down an image into seven smaller images of varying size, based
1581on an 8x8 grid.
1582
1583libpng can fill out those images or it can give them to you "as is".
1584If you want them filled out, there are two ways to do that. The one
1585mentioned in the PNG specification is to expand each pixel to cover
1586those pixels that have not been read yet (the "rectangle" method).
1587This results in a blocky image for the first pass, which gradually
1588smooths out as more pixels are read. The other method is the "sparkle"
1589method, where pixels are drawn only in their final locations, with the
1590rest of the image remaining whatever colors they were initialized to
1591before the start of the read. The first method usually looks better,
1592but tends to be slower, as there are more pixels to put in the rows.
1593
1594If you don't want libpng to handle the interlacing details, just call
1595png_read_rows() seven times to read in all seven images. Each of the
1596images is a valid image by itself, or they can all be combined on an
15978x8 grid to form a single image (although if you intend to combine them
1598you would be far better off using the libpng interlace handling).
1599
1600The first pass will return an image 1/8 as wide as the entire image
1601(every 8th column starting in column 0) and 1/8 as high as the original
1602(every 8th row starting in row 0), the second will be 1/8 as wide
1603(starting in column 4) and 1/8 as high (also starting in row 0). The
1604third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
16051/8 as high (every 8th row starting in row 4), and the fourth pass will
1606be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
1607and every 4th row starting in row 0). The fifth pass will return an
1608image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
1609while the sixth pass will be 1/2 as wide and 1/2 as high as the original
1610(starting in column 1 and row 0). The seventh and final pass will be as
1611wide as the original, and 1/2 as high, containing all of the odd
1612numbered scanlines. Phew!
1613
1614If you want libpng to expand the images, call this before calling
1615png_start_read_image() or png_read_update_info():
1616
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1617 if (interlace_type == PNG_INTERLACE_ADAM7)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1618 number_of_passes
1619 = png_set_interlace_handling(png_ptr);
1620
1621This will return the number of passes needed. Currently, this
1622is seven, but may change if another interlace type is added.
1623This function can be called even if the file is not interlaced,
1624where it will return one pass.
1625
1626If you are not going to display the image after each pass, but are
1627going to wait until the entire image is read in, use the sparkle
1628effect. This effect is faster and the end result of either method
1629is exactly the same. If you are planning on displaying the image
1630after each pass, the "rectangle" effect is generally considered the
1631better looking one.
1632
1633If you only want the "sparkle" effect, just call png_read_rows() as
1634normal, with the third parameter NULL. Make sure you make pass over
1635the image number_of_passes times, and you don't change the data in the
1636rows between calls. You can change the locations of the data, just
1637not the data. Each pass only writes the pixels appropriate for that
1638pass, and assumes the data from previous passes is still valid.
1639
1640 png_read_rows(png_ptr, row_pointers, NULL,
1641 number_of_rows);
1642
1643If you only want the first effect (the rectangles), do the same as
1644before except pass the row buffer in the third parameter, and leave
1645the second parameter NULL.
1646
1647 png_read_rows(png_ptr, NULL, row_pointers,
1648 number_of_rows);
1649
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1650.SS Finishing a sequential read
1651
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]1652After you are finished reading the image through the
1653low-level interface, you can finish reading the file. If you are
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1654interested in comments or time, which may be stored either before or
1655after the image data, you should pass the separate png_info struct if
1656you want to keep the comments from before and after the image
1657separate. If you are not interested, you can pass NULL.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1658
1659 png_read_end(png_ptr, end_info);
1660
1661When you are done, you can free all memory allocated by libpng like this:
1662
1663 png_destroy_read_struct(&png_ptr, &info_ptr,
1664 &end_info);
1665
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1666It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]1667point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1668
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1669 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1670 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]1671 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1672 more of
1673 PNG_FREE_PLTE, PNG_FREE_TRNS,
1674 PNG_FREE_HIST, PNG_FREE_ICCP,
1675 PNG_FREE_PCAL, PNG_FREE_ROWS,
1676 PNG_FREE_SCAL, PNG_FREE_SPLT,
1677 PNG_FREE_TEXT, PNG_FREE_UNKN,
1678 or simply PNG_FREE_ALL
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1679 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1680 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1681
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]1682This function may be safely called when the relevant storage has
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]1683already been freed, or has not yet been allocated, or was allocated
1684by the user and not by libpng, and will in those
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1685cases do nothing. The "seq" parameter is ignored if only one item
1686of the selected data type, such as PLTE, is allowed. If "seq" is not
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]1687-1, and multiple items are allowed for the data type identified in
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]1688the mask, such as text or sPLT, only the n'th item in the structure
1689is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]1690
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]1691The default behavior is only to free data that was allocated internally
1692by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1693or so that it will free data that was allocated by the user with png_malloc()
1694or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]1695
1696 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1697 mask - which data elements are affected
1698 same choices as in png_free_data()
1699 freer - one of
1700 PNG_DESTROY_WILL_FREE_DATA
1701 PNG_SET_WILL_FREE_DATA
1702 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]1703
1704This function only affects data that has already been allocated.
1705You can call this function after reading the PNG data but before calling
1706any png_set_*() functions, to control whether the user or the png_set_*()
1707function is responsible for freeing any existing data that might be present,
1708and again after the png_set_*() functions to control whether the user
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1709or png_destroy_*() is supposed to free the data. When the user assumes
1710responsibility for libpng-allocated data, the application must use
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1711png_free() to free it, and when the user transfers responsibility to libpng
1712for data that the user has allocated, the user must have used png_malloc()
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]1713or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]1714
1715If you allocated your row_pointers in a single block, as suggested above in
1716the description of the high level read interface, you must not transfer
1717responsibility for freeing it to the png_set_rows or png_read_destroy function,
1718because they would also try to free the individual row_pointers[i].
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]1719
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]1720If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
1721separately, do not transfer responsibility for freeing text_ptr to libpng,
1722because when libpng fills a png_text structure it combines these members with
1723the key member, and png_free_data() will free only text_ptr.key. Similarly,
1724if you transfer responsibility for free'ing text_ptr from libpng to your
1725application, your application must not separately free those members.
1726
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]1727The png_free_data() function will turn off the "valid" flag for anything
1728it frees. If you need to turn the flag off for a chunk that was freed by your
1729application instead of by libpng, you can use
1730
1731 png_set_invalid(png_ptr, info_ptr, mask);
1732 mask - identifies the chunks to be made invalid,
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]1733 containing the bitwise OR of one or
Glenn Randers-Pehrsond56aca72000-11-23 11:51:42 -0600[diff] [blame]1734 more of
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]1735 PNG_INFO_gAMA, PNG_INFO_sBIT,
1736 PNG_INFO_cHRM, PNG_INFO_PLTE,
1737 PNG_INFO_tRNS, PNG_INFO_bKGD,
1738 PNG_INFO_hIST, PNG_INFO_pHYs,
1739 PNG_INFO_oFFs, PNG_INFO_tIME,
1740 PNG_INFO_pCAL, PNG_INFO_sRGB,
1741 PNG_INFO_iCCP, PNG_INFO_sPLT,
1742 PNG_INFO_sCAL, PNG_INFO_IDAT
1743
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1744For a more compact example of reading a PNG image, see the file example.c.
1745
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1746.SS Reading PNG files progressively
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1747
1748The progressive reader is slightly different then the non-progressive
1749reader. Instead of calling png_read_info(), png_read_rows(), and
1750png_read_end(), you make one call to png_process_data(), which calls
1751callbacks when it has the info, a row, or the end of the image. You
1752set up these callbacks with png_set_progressive_read_fn(). You don't
1753have to worry about the input/output functions of libpng, as you are
1754giving the library the data directly in png_process_data(). I will
1755assume that you have read the section on reading PNG files above,
1756so I will only highlight the differences (although I will show
1757all of the code).
1758
1759png_structp png_ptr;
1760png_infop info_ptr;
1761
1762 /* An example code fragment of how you would
1763 initialize the progressive reader in your
1764 application. */
1765 int
1766 initialize_png_reader()
1767 {
1768 png_ptr = png_create_read_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]1769 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1770 user_error_fn, user_warning_fn);
1771 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1772 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1773 info_ptr = png_create_info_struct(png_ptr);
1774 if (!info_ptr)
1775 {
1776 png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
1777 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1778 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1779 }
1780
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1781 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1782 {
1783 png_destroy_read_struct(&png_ptr, &info_ptr,
1784 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1785 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1786 }
1787
1788 /* This one's new. You can provide functions
1789 to be called when the header info is valid,
1790 when each row is completed, and when the image
1791 is finished. If you aren't using all functions,
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1792 you can specify NULL parameters. Even when all
1793 three functions are NULL, you need to call
1794 png_set_progressive_read_fn(). You can use
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1795 any struct as the user_ptr (cast to a void pointer
1796 for the function call), and retrieve the pointer
1797 from inside the callbacks using the function
1798
1799 png_get_progressive_ptr(png_ptr);
1800
1801 which will return a void pointer, which you have
1802 to cast appropriately.
1803 */
1804 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
1805 info_callback, row_callback, end_callback);
1806
1807 return 0;
1808 }
1809
1810 /* A code fragment that you call as you receive blocks
1811 of data */
1812 int
1813 process_data(png_bytep buffer, png_uint_32 length)
1814 {
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1815 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1816 {
1817 png_destroy_read_struct(&png_ptr, &info_ptr,
1818 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1819 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1820 }
1821
1822 /* This one's new also. Simply give it a chunk
1823 of data from the file stream (in order, of
1824 course). On machines with segmented memory
1825 models machines, don't give it any more than
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1826 64K. The library seems to run fine with sizes
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1827 of 4K. Although you can give it much less if
1828 necessary (I assume you can give it chunks of
1829 1 byte, I haven't tried less then 256 bytes
1830 yet). When this function returns, you may
1831 want to display any rows that were generated
1832 in the row callback if you don't already do
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1833 so there.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1834 */
1835 png_process_data(png_ptr, info_ptr, buffer, length);
1836 return 0;
1837 }
1838
1839 /* This function is called (as set by
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1840 png_set_progressive_read_fn() above) when enough data
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1841 has been supplied so all of the header has been
1842 read.
1843 */
1844 void
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1845 info_callback(png_structp png_ptr, png_infop info)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1846 {
1847 /* Do any setup here, including setting any of
1848 the transformations mentioned in the Reading
1849 PNG files section. For now, you _must_ call
1850 either png_start_read_image() or
1851 png_read_update_info() after all the
1852 transformations are set (even if you don't set
1853 any). You may start getting rows before
1854 png_process_data() returns, so this is your
1855 last chance to prepare for that.
1856 */
1857 }
1858
1859 /* This function is called when each row of image
1860 data is complete */
1861 void
1862 row_callback(png_structp png_ptr, png_bytep new_row,
Glenn Randers-Pehrsone68f5a32001-05-14 09:20:53 -0500[diff] [blame]1863 png_uint_32 row_num, int pass)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1864 {
1865 /* If the image is interlaced, and you turned
1866 on the interlace handler, this function will
1867 be called for every row in every pass. Some
1868 of these rows will not be changed from the
1869 previous pass. When the row is not changed,
1870 the new_row variable will be NULL. The rows
1871 and passes are called in order, so you don't
1872 really need the row_num and pass, but I'm
1873 supplying them because it may make your life
1874 easier.
1875
1876 For the non-NULL rows of interlaced images,
1877 you must call png_progressive_combine_row()
1878 passing in the row and the old row. You can
1879 call this function for NULL rows (it will just
1880 return) and for non-interlaced images (it just
1881 does the memcpy for you) if it will make the
1882 code easier. Thus, you can just do this for
1883 all cases:
1884 */
1885
1886 png_progressive_combine_row(png_ptr, old_row,
1887 new_row);
1888
1889 /* where old_row is what was displayed for
Glenn Randers-Pehrson345bc271998-06-14 14:43:31 -0500[diff] [blame]1890 previously for the row. Note that the first
1891 pass (pass == 0, really) will completely cover
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1892 the old row, so the rows do not have to be
1893 initialized. After the first pass (and only
1894 for interlaced images), you will have to pass
1895 the current row, and the function will combine
1896 the old row and the new row.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1897 */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1898 }
1899
1900 void
1901 end_callback(png_structp png_ptr, png_infop info)
1902 {
1903 /* This function is called after the whole image
1904 has been read, including any chunks after the
1905 image (up to and including the IEND). You
1906 will usually have the same info chunk as you
1907 had in the header, although some data may have
1908 been added to the comments and time fields.
1909
1910 Most people won't do much here, perhaps setting
1911 a flag that marks the image as finished.
1912 */
1913 }
1914
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]1915
1916
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]1917.SH IV. Writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1918
1919Much of this is very similar to reading. However, everything of
1920importance is repeated here, so you won't have to constantly look
1921back up in the reading section to understand writing.
1922
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1923.SS Setup
1924
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1925You will want to do the I/O initialization before you get into libpng,
1926so if it doesn't work, you don't have anything to undo. If you are not
1927using the standard I/O functions, you will need to replace them with
1928custom writing functions. See the discussion under Customizing libpng.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1929
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1930 FILE *fp = fopen(file_name, "wb");
1931 if (!fp)
1932 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1933 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1934 }
1935
1936Next, png_struct and png_info need to be allocated and initialized.
1937As these can be both relatively large, you may not want to store these
1938on the stack, unless you have stack space to spare. Of course, you
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]1939will want to check if they return NULL. If you are also reading,
1940you won't want to name your read structure and your write structure
1941both "png_ptr"; you can call them anything you like, such as
1942"read_ptr" and "write_ptr". Look at pngtest.c, for example.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1943
1944 png_structp png_ptr = png_create_write_struct
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]1945 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1946 user_error_fn, user_warning_fn);
1947 if (!png_ptr)
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1948 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1949
1950 png_infop info_ptr = png_create_info_struct(png_ptr);
1951 if (!info_ptr)
1952 {
1953 png_destroy_write_struct(&png_ptr,
1954 (png_infopp)NULL);
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1955 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1956 }
1957
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1958If you want to use your own memory allocation routines,
1959define PNG_USER_MEM_SUPPORTED and use
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]1960png_create_write_struct_2() instead of png_create_write_struct():
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]1961
1962 png_structp png_ptr = png_create_write_struct_2
1963 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
1964 user_error_fn, user_warning_fn, (png_voidp)
1965 user_mem_ptr, user_malloc_fn, user_free_fn);
1966
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1967After you have these structures, you will need to set up the
1968error handling. When libpng encounters an error, it expects to
1969longjmp() back to your routine. Therefore, you will need to call
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1970setjmp() and pass the png_jmpbuf(png_ptr). If you
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1971write the file from different routines, you will need to update
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1972the png_jmpbuf(png_ptr) every time you enter a new routine that will
1973call a png_*() function. See your documentation of setjmp/longjmp
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1974for your compiler for more information on setjmp/longjmp. See
1975the discussion on libpng error handling in the Customizing Libpng
1976section below for more information on the libpng error handling.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1977
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]1978 if (setjmp(png_jmpbuf(png_ptr)))
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1979 {
Glenn Randers-Pehrson104622b2000-05-29 08:58:03 -0500[diff] [blame]1980 png_destroy_write_struct(&png_ptr, &info_ptr);
1981 fclose(fp);
1982 return (ERROR);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1983 }
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]1984 ...
1985 return;
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1986
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]1987If you would rather avoid the complexity of setjmp/longjmp issues,
1988you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
1989errors will result in a call to PNG_ABORT() which defaults to abort().
1990
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]1991Now you need to set up the output code. The default for libpng is to
1992use the C function fwrite(). If you use this, you will need to pass a
1993valid FILE * in the function png_init_io(). Be sure that the file is
1994opened in binary mode. Again, if you wish to handle writing data in
1995another way, see the discussion on libpng I/O handling in the Customizing
1996Libpng section below.
1997
1998 png_init_io(png_ptr, fp);
1999
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]2000If you are embedding your PNG into a datastream such as MNG, and don't
2001want libpng to write the 8-byte signature, or if you have already
2002written the signature in your application, use
2003
2004 png_set_sig_bytes(png_ptr, 8);
2005
2006to inform libpng that it should not write a signature.
2007
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2008.SS Write callbacks
2009
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2010At this point, you can set up a callback function that will be
2011called after each row has been written, which you can use to control
2012a progress meter or the like. It's demonstrated in pngtest.c.
2013You must supply a function
2014
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2015 void write_row_callback(png_ptr, png_uint_32 row,
2016 int pass);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2017 {
2018 /* put your code here */
2019 }
2020
2021(You can give it another name that you like instead of "write_row_callback")
2022
2023To inform libpng about your function, use
2024
2025 png_set_write_status_fn(png_ptr, write_row_callback);
2026
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2027You now have the option of modifying how the compression library will
2028run. The following functions are mainly for testing, but may be useful
2029in some cases, like if you need to write PNG files extremely fast and
2030are willing to give up some compression, or if you want to get the
2031maximum possible compression at the expense of slower writing. If you
2032have no special needs in this area, let the library do what it wants by
2033not calling this function at all, as it has been tuned to deliver a good
2034speed/compression ratio. The second parameter to png_set_filter() is
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2035the filter method, for which the only valid values are 0 (as of the
2036July 1999 PNG specification, version 1.2) or 64 (if you are writing
2037a PNG datastream that is to be embedded in a MNG datastream). The third
2038parameter is a flag that indicates which filter type(s) are to be tested
2039for each scanline. See the PNG specification for details on the specific filter
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2040types.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2041
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2042
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2043 /* turn on or off filtering, and/or choose
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2044 specific filters. You can use either a single
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2045 PNG_FILTER_VALUE_NAME or the bitwise OR of one
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2046 or more PNG_FILTER_NAME masks. */
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2047 png_set_filter(png_ptr, 0,
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2048 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
2049 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
2050 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
2051 PNG_FILTER_AVE | PNG_FILTER_VALUE_AVE |
2052 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2053 PNG_ALL_FILTERS);
2054
2055If an application
2056wants to start and stop using particular filters during compression,
2057it should start out with all of the filters (to ensure that the previous
2058row of pixels will be stored in case it's needed later), and then add
2059and remove them after the start of compression.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2060
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2061If you are writing a PNG datastream that is to be embedded in a MNG
2062datastream, the second parameter can be either 0 or 64.
2063
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2064The png_set_compression_*() functions interface to the zlib compression
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2065library, and should mostly be ignored unless you really know what you are
2066doing. The only generally useful call is png_set_compression_level()
2067which changes how much time zlib spends on trying to compress the image
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2068data. See the Compression Library (zlib.h and algorithm.txt, distributed
2069with zlib) for details on the compression levels.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2070
2071 /* set the zlib compression level */
2072 png_set_compression_level(png_ptr,
2073 Z_BEST_COMPRESSION);
2074
2075 /* set other zlib parameters */
2076 png_set_compression_mem_level(png_ptr, 8);
2077 png_set_compression_strategy(png_ptr,
2078 Z_DEFAULT_STRATEGY);
2079 png_set_compression_window_bits(png_ptr, 15);
2080 png_set_compression_method(png_ptr, 8);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2081 png_set_compression_buffer_size(png_ptr, 8192)
2082
2083extern PNG_EXPORT(void,png_set_zbuf_size)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2084
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2085.SS Setting the contents of info for output
2086
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2087You now need to fill in the png_info structure with all the data you
2088wish to write before the actual image. Note that the only thing you
2089are allowed to write after the image is the text chunks and the time
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2090chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2091the latest PNG specification for more information on that. If you
2092wish to write them before the image, fill them in now, and flag that
2093data as being valid. If you want to wait until after the data, don't
2094fill them until png_write_end(). For all the fields in png_info and
2095their data types, see png.h. For explanations of what the fields
2096contain, see the PNG specification.
2097
2098Some of the more important parts of the png_info are:
2099
2100 png_set_IHDR(png_ptr, info_ptr, width, height,
2101 bit_depth, color_type, interlace_type,
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2102 compression_type, filter_method)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2103 width - holds the width of the image
2104 in pixels (up to 2^31).
2105 height - holds the height of the image
2106 in pixels (up to 2^31).
2107 bit_depth - holds the bit depth of one of the
2108 image channels.
2109 (valid values are 1, 2, 4, 8, 16
2110 and depend also on the
2111 color_type. See also significant
2112 bits (sBIT) below).
2113 color_type - describes which color/alpha
2114 channels are present.
2115 PNG_COLOR_TYPE_GRAY
2116 (bit depths 1, 2, 4, 8, 16)
2117 PNG_COLOR_TYPE_GRAY_ALPHA
2118 (bit depths 8, 16)
2119 PNG_COLOR_TYPE_PALETTE
2120 (bit depths 1, 2, 4, 8)
2121 PNG_COLOR_TYPE_RGB
2122 (bit_depths 8, 16)
2123 PNG_COLOR_TYPE_RGB_ALPHA
2124 (bit_depths 8, 16)
2125
2126 PNG_COLOR_MASK_PALETTE
2127 PNG_COLOR_MASK_COLOR
2128 PNG_COLOR_MASK_ALPHA
2129
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2130 interlace_type - PNG_INTERLACE_NONE or
2131 PNG_INTERLACE_ADAM7
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2132 compression_type - (must be
2133 PNG_COMPRESSION_TYPE_DEFAULT)
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]2134 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
2135 or, if you are writing a PNG to
2136 be embedded in a MNG datastream,
2137 can also be
2138 PNG_INTRAPIXEL_DIFFERENCING)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2139
2140 png_set_PLTE(png_ptr, info_ptr, palette,
2141 num_palette);
2142 palette - the palette for the file
2143 (array of png_color)
2144 num_palette - number of entries in the palette
2145
2146 png_set_gAMA(png_ptr, info_ptr, gamma);
2147 gamma - the gamma the image was created
2148 at (PNG_INFO_gAMA)
2149
2150 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2151 srgb_intent - the rendering intent
2152 (PNG_INFO_sRGB) The presence of
2153 the sRGB chunk means that the pixel
2154 data is in the sRGB color space.
2155 This chunk also implies specific
2156 values of gAMA and cHRM. Rendering
2157 intent is the CSS-1 property that
2158 has been defined by the International
2159 Color Consortium
2160 (http://www.color.org).
2161 It can be one of
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]2162 PNG_sRGB_INTENT_SATURATION,
2163 PNG_sRGB_INTENT_PERCEPTUAL,
2164 PNG_sRGB_INTENT_ABSOLUTE, or
2165 PNG_sRGB_INTENT_RELATIVE.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2166
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2167
2168 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2169 srgb_intent);
2170 srgb_intent - the rendering intent
2171 (PNG_INFO_sRGB) The presence of the
2172 sRGB chunk means that the pixel
2173 data is in the sRGB color space.
2174 This function also causes gAMA and
2175 cHRM chunks with the specific values
2176 that are consistent with sRGB to be
2177 written.
2178
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2179 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2180 profile, proflen);
2181 name - The profile name.
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2182 compression - The compression type; always
2183 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2184 You may give NULL to this argument to
2185 ignore it.
2186 profile - International Color Consortium color
2187 profile data. May contain NULs.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2188 proflen - length of profile data in bytes.
2189
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2190 png_set_sBIT(png_ptr, info_ptr, sig_bit);
2191 sig_bit - the number of significant bits for
2192 (PNG_INFO_sBIT) each of the gray, red,
2193 green, and blue channels, whichever are
2194 appropriate for the given color type
2195 (png_color_16)
2196
2197 png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
2198 trans_values);
2199 trans - array of transparent entries for
2200 palette (PNG_INFO_tRNS)
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]2201 trans_values - graylevel or color sample values of
2202 the single transparent color for
2203 non-paletted images (PNG_INFO_tRNS)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2204 num_trans - number of transparent entries
2205 (PNG_INFO_tRNS)
2206
2207 png_set_hIST(png_ptr, info_ptr, hist);
2208 (PNG_INFO_hIST)
2209 hist - histogram of palette (array of
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2210 png_uint_16)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2211
2212 png_set_tIME(png_ptr, info_ptr, mod_time);
2213 mod_time - time image was last modified
2214 (PNG_VALID_tIME)
2215
2216 png_set_bKGD(png_ptr, info_ptr, background);
2217 background - background color (PNG_VALID_bKGD)
2218
2219 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2220 text_ptr - array of png_text holding image
2221 comments
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2222 text_ptr[i].compression - type of compression used
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2223 on "text" PNG_TEXT_COMPRESSION_NONE
2224 PNG_TEXT_COMPRESSION_zTXt
2225 PNG_ITXT_COMPRESSION_NONE
2226 PNG_ITXT_COMPRESSION_zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2227 text_ptr[i].key - keyword for comment. Must contain
2228 1-79 characters.
2229 text_ptr[i].text - text comments for current
2230 keyword. Can be NULL or empty.
2231 text_ptr[i].text_length - length of text string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2232 after decompression, 0 for iTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2233 text_ptr[i].itxt_length - length of itxt string,
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2234 after decompression, 0 for tEXt/zTXt
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2235 text_ptr[i].lang - language of comment (NULL or
2236 empty for unknown).
2237 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
2238 or empty for unknown).
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2239 num_text - number of comments
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2240
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2241 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2242 num_spalettes);
2243 palette_ptr - array of png_sPLT_struct structures
2244 to be added to the list of palettes
2245 in the info structure.
2246 num_spalettes - number of palette structures to be
2247 added.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2248
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2249 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2250 unit_type);
2251 offset_x - positive offset from the left
2252 edge of the screen
2253 offset_y - positive offset from the top
2254 edge of the screen
2255 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2256
2257 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2258 unit_type);
2259 res_x - pixels/unit physical resolution
2260 in x direction
2261 res_y - pixels/unit physical resolution
2262 in y direction
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2263 unit_type - PNG_RESOLUTION_UNKNOWN,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2264 PNG_RESOLUTION_METER
2265
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2266 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2267 unit - physical scale units (an integer)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2268 width - width of a pixel in physical scale units
2269 height - height of a pixel in physical scale units
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2270 (width and height are doubles)
2271
2272 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2273 unit - physical scale units (an integer)
2274 width - width of a pixel in physical scale units
2275 height - height of a pixel in physical scale units
2276 (width and height are strings like "2.54")
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2277
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2278 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2279 num_unknowns)
2280 unknowns - array of png_unknown_chunk
2281 structures holding unknown chunks
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2282 unknowns[i].name - name of unknown chunk
2283 unknowns[i].data - data of unknown chunk
Glenn Randers-Pehrson4accabb2000-04-14 14:20:47 -0500[diff] [blame]2284 unknowns[i].size - size of unknown chunk's data
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2285 unknowns[i].location - position to write chunk in file
2286 0: do not write chunk
2287 PNG_HAVE_IHDR: before PLTE
2288 PNG_HAVE_PLTE: before IDAT
2289 PNG_AFTER_IDAT: after IDAT
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2290
2291The "location" member is set automatically according to
2292what part of the output file has already been written.
2293You can change its value after calling png_set_unknown_chunks()
2294as demonstrated in pngtest.c. Within each of the "locations",
2295the chunks are sequenced according to their position in the
2296structure (that is, the value of "i", which is the order in which
2297the chunk was either read from the input file or defined with
2298png_set_unknown_chunks).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2299
2300A quick word about text and num_text. text is an array of png_text
2301structures. num_text is the number of valid structures in the array.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2302Each png_text structure holds a language code, a keyword, a text value,
2303and a compression type.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2304
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2305The compression types have the same valid numbers as the compression
2306types of the image data. Currently, the only valid number is zero.
2307However, you can store text either compressed or uncompressed, unlike
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2308images, which always have to be compressed. So if you don't want the
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2309text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2310Because tEXt and zTXt chunks don't have a language field, if you
2311specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
2312any language code or translated keyword will not be written out.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2313
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2314Until text gets around 1000 bytes, it is not worth compressing it.
2315After the text has been written out to the file, the compression type
2316is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2317so that it isn't written out again at the end (in case you are calling
2318png_write_end() with the same struct.
2319
2320The keywords that are given in the PNG Specification are:
2321
2322 Title Short (one line) title or
2323 caption for image
2324 Author Name of image's creator
2325 Description Description of image (possibly long)
2326 Copyright Copyright notice
2327 Creation Time Time of original image creation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2328 (usually RFC 1123 format, see below)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2329 Software Software used to create the image
2330 Disclaimer Legal disclaimer
2331 Warning Warning of nature of content
2332 Source Device used to create the image
2333 Comment Miscellaneous comment; conversion
2334 from other image format
2335
2336The keyword-text pairs work like this. Keywords should be short
2337simple descriptions of what the comment is about. Some typical
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2338keywords are found in the PNG specification, as is some recommendations
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2339on keywords. You can repeat keywords in a file. You can even write
2340some text before the image and some after. For example, you may want
2341to put a description of the image before the image, but leave the
2342disclaimer until after, so viewers working over modem connections
2343don't have to wait for the disclaimer to go over the modem before
2344they start seeing the image. Finally, keywords should be full
2345words, not abbreviations. Keywords and text are in the ISO 8859-1
2346(Latin-1) character set (a superset of regular ASCII) and can not
2347contain NUL characters, and should not contain control or other
2348unprintable characters. To make the comments widely readable, stick
2349with basic ASCII, and avoid machine specific character set extensions
2350like the IBM-PC character set. The keyword must be present, but
2351you can leave off the text string on non-compressed pairs.
2352Compressed pairs must have a text string, as only the text string
2353is compressed anyway, so the compression would be meaningless.
2354
2355PNG supports modification time via the png_time structure. Two
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2356conversion routines are provided, png_convert_from_time_t() for
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2357time_t and png_convert_from_struct_tm() for struct tm. The
2358time_t routine uses gmtime(). You don't have to use either of
2359these, but if you wish to fill in the png_time structure directly,
2360you should provide the time in universal time (GMT) if possible
2361instead of your local time. Note that the year number is the full
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2362year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2363that months start with 1.
2364
2365If you want to store the time of the original image creation, you should
2366use a plain tEXt chunk with the "Creation Time" keyword. This is
2367necessary because the "creation time" of a PNG image is somewhat vague,
2368depending on whether you mean the PNG file, the time the image was
2369created in a non-PNG format, a still photo from which the image was
2370scanned, or possibly the subject matter itself. In order to facilitate
2371machine-readable dates, it is recommended that the "Creation Time"
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2372tEXt 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]2373although this isn't a requirement. Unlike the tIME chunk, the
2374"Creation Time" tEXt chunk is not expected to be automatically changed
2375by the software. To facilitate the use of RFC 1123 dates, a function
2376png_convert_to_rfc1123(png_timep) is provided to convert from PNG
2377time to an RFC 1123 format string.
2378
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2379.SS Writing unknown chunks
2380
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2381You can use the png_set_unknown_chunks function to queue up chunks
2382for writing. You give it a chunk name, raw data, and a size; that's
2383all there is to it. The chunks will be written by the next following
2384png_write_info_before_PLTE, png_write_info, or png_write_end function.
2385Any chunks previously read into the info structure's unknown-chunk
2386list will also be written out in a sequence that satisfies the PNG
2387specification's ordering rules.
2388
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2389.SS The high-level write interface
2390
2391At this point there are two ways to proceed; through the high-level
2392write interface, or through a sequence of low-level write operations.
2393You can use the high-level interface if your image data is present
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2394in the info structure. All defined output
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2395transformations are permitted, enabled by the following masks.
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2396
2397 PNG_TRANSFORM_IDENTITY No transformation
2398 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2399 PNG_TRANSFORM_PACKSWAP Change order of packed
2400 pixels to LSB first
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2401 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2402 PNG_TRANSFORM_SHIFT Normalize pixels to the
2403 sBIT depth
2404 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
2405 to BGRA
2406 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
2407 to AG
2408 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
2409 to transparency
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2410 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
2411 PNG_TRANSFORM_STRIP_FILLER Strip out filler bytes.
2412
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2413If you have valid image data in the info structure (you can use
2414png_set_rows() to put image data in the info structure), simply do this:
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2415
2416 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
2417
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2418where png_transforms is an integer containing the bitwise OR of some set of
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2419transformation flags. This call is equivalent to png_write_info(),
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2420followed the set of transformations indicated by the transform mask,
2421then png_write_image(), and finally png_write_end().
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2422
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2423(The final parameter of this call is not yet used. Someday it might point
2424to transformation parameters required by some future output transform.)
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2425
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]2426You must use png_transforms and not call any png_set_transform() functions
2427when you use png_write_png().
2428
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2429.SS The low-level write interface
2430
2431If you are going the low-level route instead, you are now ready to
2432write all the file information up to the actual image data. You do
2433this with a call to png_write_info().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2434
2435 png_write_info(png_ptr, info_ptr);
2436
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2437Note that there is one transformation you may need to do before
2438png_write_info(). In PNG files, the alpha channel in an image is the
2439level of opacity. If your data is supplied as a level of
2440transparency, you can invert the alpha channel before you write it, so
2441that 0 is fully transparent and 255 (in 8-bit or paletted images) or
244265535 (in 16-bit images) is fully opaque, with
2443
2444 png_set_invert_alpha(png_ptr);
2445
2446This must appear before png_write_info() instead of later with the
2447other transformations because in the case of paletted images the tRNS
2448chunk data has to be inverted before the tRNS chunk is written. If
2449your image is not a paletted image, the tRNS data (which in such cases
2450represents a single color to be rendered as transparent) won't need to
2451be changed, and you can safely do this transformation after your
2452png_write_info() call.
2453
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]2454If you need to write a private chunk that you want to appear before
2455the PLTE chunk when PLTE is present, you can write the PNG info in
2456two steps, and insert code to write your own chunk between them:
2457
2458 png_write_info_before_PLTE(png_ptr, info_ptr);
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2459 png_set_unknown_chunks(png_ptr, info_ptr, ...);
Glenn Randers-Pehrson5379b241999-11-27 10:22:33 -0600[diff] [blame]2460 png_write_info(png_ptr, info_ptr);
2461
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2462After you've written the file information, you can set up the library
2463to handle any special transformations of the image data. The various
2464ways to transform the data will be described in the order that they
2465should occur. This is important, as some of these change the color
2466type and/or bit depth of the data, and some others only work on
2467certain color types and bit depths. Even though each transformation
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2468checks 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]2469make sure to only enable a transformation if it will be valid for the
2470data. For example, don't swap red and blue on grayscale data.
2471
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2472PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]2473the 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]2474to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
2475bytes per pixel).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2476
2477 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
2478
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2479where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2480PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
2481is stored XRGB or RGBX.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2482
2483PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
2484they can, resulting in, for example, 8 pixels per byte for 1 bit files.
2485If the data is supplied at 1 pixel per byte, use this code, which will
2486correctly pack the pixels into a single byte:
2487
2488 png_set_packing(png_ptr);
2489
2490PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
2491data is of another bit depth, you can write an sBIT chunk into the
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2492file so that decoders can recover the original data if desired.
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2493
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2494 /* Set the true bit depth of the image data */
2495 if (color_type & PNG_COLOR_MASK_COLOR)
2496 {
2497 sig_bit.red = true_bit_depth;
2498 sig_bit.green = true_bit_depth;
2499 sig_bit.blue = true_bit_depth;
2500 }
2501 else
2502 {
2503 sig_bit.gray = true_bit_depth;
2504 }
2505 if (color_type & PNG_COLOR_MASK_ALPHA)
2506 {
2507 sig_bit.alpha = true_bit_depth;
2508 }
2509
2510 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
2511
2512If 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]2513one 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]2514this will scale the values to appear to be the correct bit depth as
2515is required by PNG.
2516
2517 png_set_shift(png_ptr, &sig_bit);
2518
2519PNG files store 16 bit pixels in network byte order (big-endian,
2520ie. most significant bits first). This code would be used if they are
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2521supplied the other way (little-endian, i.e. least significant bits
2522first, the way PCs store them):
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2523
2524 if (bit_depth > 8)
2525 png_set_swap(png_ptr);
2526
2527If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2528need to change the order the pixels are packed into bytes, you can use:
2529
2530 if (bit_depth < 8)
2531 png_set_packswap(png_ptr);
2532
2533PNG files store 3 color pixels in red, green, blue order. This code
2534would be used if they are supplied as blue, green, red:
2535
2536 png_set_bgr(png_ptr);
2537
2538PNG files describe monochrome as black being zero and white being
2539one. This code would be used if the pixels are supplied with this reversed
2540(black being one and white being zero):
2541
2542 png_set_invert_mono(png_ptr);
2543
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2544Finally, you can write your own transformation function if none of
2545the existing ones meets your needs. This is done by setting a callback
2546with
2547
2548 png_set_write_user_transform_fn(png_ptr,
2549 write_transform_fn);
2550
2551You must supply the function
2552
2553 void write_transform_fn(png_ptr ptr, row_info_ptr
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2554 row_info, png_bytep data)
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2555
2556See pngtest.c for a working example. Your function will be called
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2557before any of the other transformations are processed.
2558
2559You can also set up a pointer to a user structure for use by your
2560callback function.
2561
2562 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
2563
2564The user_channels and user_depth parameters of this function are ignored
2565when writing; you can set them to zero as shown.
2566
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2567You can retrieve the pointer via the function png_get_user_transform_ptr().
2568For example:
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2569
2570 voidp write_user_transform_ptr =
2571 png_get_user_transform_ptr(png_ptr);
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]2572
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2573It is possible to have libpng flush any pending output, either manually,
2574or automatically after a certain number of lines have been written. To
2575flush the output stream a single time call:
2576
2577 png_write_flush(png_ptr);
2578
2579and to have libpng flush the output stream periodically after a certain
2580number of scanlines have been written, call:
2581
2582 png_set_flush(png_ptr, nrows);
2583
2584Note that the distance between rows is from the last time png_write_flush()
2585was called, or the first row of the image if it has never been called.
2586So if you write 50 lines, and then png_set_flush 25, it will flush the
2587output on the next scanline, and every 25 lines thereafter, unless
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2588png_write_flush() is called before 25 more lines have been written.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2589If 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]2590RGB image) the image compression may decrease noticeably (although this
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2591may be acceptable for real-time applications). Infrequent flushing will
2592only degrade the compression performance by a few percent over images
2593that do not use flushing.
2594
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2595.SS Writing the image data
2596
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2597That's it for the transformations. Now you can write the image data.
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2598The 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]2599whole image in memory, you can just call png_write_image() and libpng
2600will write the image. You will need to pass in an array of pointers to
2601each row. This function automatically handles interlacing, so you don't
2602need to call png_set_interlace_handling() or call this function multiple
2603times, or any of that other stuff necessary with png_write_rows().
2604
2605 png_write_image(png_ptr, row_pointers);
2606
2607where row_pointers is:
2608
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2609 png_byte *row_pointers[height];
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2610
2611You can point to void or char or whatever you use for pixels.
2612
Glenn Randers-Pehrson896239b1998-04-21 15:03:57 -0500[diff] [blame]2613If you don't want to write the whole image at once, you can
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2614use png_write_rows() instead. If the file is not interlaced,
2615this is simple:
2616
2617 png_write_rows(png_ptr, row_pointers,
2618 number_of_rows);
2619
2620row_pointers is the same as in the png_write_image() call.
2621
2622If 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]2623a single row_pointer instead of an array of row_pointers:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2624
2625 png_bytep row_pointer = row;
2626
Glenn Randers-Pehrson520a7642000-03-21 05:13:06 -0600[diff] [blame]2627 png_write_row(png_ptr, row_pointer);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2628
2629When the file is interlaced, things can get a good deal more
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2630complicated. The only currently (as of the PNG Specification
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2631version 1.2, dated July 1999) defined interlacing scheme for PNG files
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2632is the "Adam7" interlace scheme, that breaks down an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2633image into seven smaller images of varying size. libpng will build
2634these images for you, or you can do them yourself. If you want to
2635build them yourself, see the PNG specification for details of which
2636pixels to write when.
2637
2638If you don't want libpng to handle the interlacing details, just
2639use png_set_interlace_handling() and call png_write_rows() the
2640correct number of times to write all seven sub-images.
2641
2642If you want libpng to build the sub-images, call this before you start
2643writing any rows:
2644
2645 number_of_passes =
2646 png_set_interlace_handling(png_ptr);
2647
2648This will return the number of passes needed. Currently, this
2649is seven, but may change if another interlace type is added.
2650
2651Then write the complete image number_of_passes times.
2652
2653 png_write_rows(png_ptr, row_pointers,
2654 number_of_rows);
2655
2656As some of these rows are not used, and thus return immediately,
2657you may want to read about interlacing in the PNG specification,
2658and only update the rows that are actually used.
2659
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2660.SS Finishing a sequential write
2661
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2662After you are finished writing the image, you should finish writing
2663the file. If you are interested in writing comments or time, you should
2664pass an appropriately filled png_info pointer. If you are not interested,
2665you can pass NULL.
2666
2667 png_write_end(png_ptr, info_ptr);
2668
2669When you are done, you can free all memory used by libpng like this:
2670
2671 png_destroy_write_struct(&png_ptr, &info_ptr);
2672
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2673It is also possible to individually free the info_ptr members that
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2674point to libpng-allocated storage with the following function:
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2675
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2676 png_free_data(png_ptr, info_ptr, mask, seq)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2677 mask - identifies data to be freed, a mask
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2678 containing the bitwise OR of one or
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2679 more of
2680 PNG_FREE_PLTE, PNG_FREE_TRNS,
2681 PNG_FREE_HIST, PNG_FREE_ICCP,
2682 PNG_FREE_PCAL, PNG_FREE_ROWS,
2683 PNG_FREE_SCAL, PNG_FREE_SPLT,
2684 PNG_FREE_TEXT, PNG_FREE_UNKN,
2685 or simply PNG_FREE_ALL
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2686 seq - sequence number of item to be freed
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2687 (-1 for all items)
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2688
Glenn Randers-Pehrsonfc4a1432000-05-17 17:39:34 -0500[diff] [blame]2689This function may be safely called when the relevant storage has
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2690already been freed, or has not yet been allocated, or was allocated
2691by the user and not by libpng, and will in those
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2692cases do nothing. The "seq" parameter is ignored if only one item
2693of the selected data type, such as PLTE, is allowed. If "seq" is not
Glenn Randers-Pehrson68ea2432000-04-01 21:10:05 -0600[diff] [blame]2694-1, and multiple items are allowed for the data type identified in
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2695the mask, such as text or sPLT, only the n'th item in the structure
2696is freed, where n is "seq".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]2697
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2698If you allocated data such as a palette that you passed
2699in to libpng with png_set_*, you must not free it until just before the call to
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2700png_destroy_write_struct().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2701
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2702The default behavior is only to free data that was allocated internally
2703by libpng. This can be changed, so that libpng will not free the data,
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2704or so that it will free data that was allocated by the user with png_malloc()
2705or png_zalloc() and passed in via a png_set_*() function, with
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2706
2707 png_data_freer(png_ptr, info_ptr, freer, mask)
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2708 mask - which data elements are affected
2709 same choices as in png_free_data()
2710 freer - one of
2711 PNG_DESTROY_WILL_FREE_DATA
2712 PNG_SET_WILL_FREE_DATA
2713 PNG_USER_WILL_FREE_DATA
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2714
2715For example, to transfer responsibility for some data from a read structure
2716to a write structure, you could use
2717
2718 png_data_freer(read_ptr, read_info_ptr,
2719 PNG_USER_WILL_FREE_DATA,
2720 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2721 png_data_freer(write_ptr, write_info_ptr,
2722 PNG_DESTROY_WILL_FREE_DATA,
2723 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
2724
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2725thereby briefly reassigning responsibility for freeing to the user but
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2726immediately afterwards reassigning it once more to the write_destroy
2727function. Having done this, it would then be safe to destroy the read
2728structure and continue to use the PLTE, tRNS, and hIST data in the write
2729structure.
2730
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2731This function only affects data that has already been allocated.
2732You can call this function before calling after the png_set_*() functions
2733to control whether the user or png_destroy_*() is supposed to free the data.
2734When the user assumes responsibility for libpng-allocated data, the
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2735application must use
2736png_free() to free it, and when the user transfers responsibility to libpng
2737for data that the user has allocated, the user must have used png_malloc()
2738or png_zalloc() to allocate it.
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2739
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]2740If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2741separately, do not transfer responsibility for freeing text_ptr to libpng,
2742because when libpng fills a png_text structure it combines these members with
2743the key member, and png_free_data() will free only text_ptr.key. Similarly,
2744if you transfer responsibility for free'ing text_ptr from libpng to your
2745application, your application must not separately free those members.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2746For a more compact example of writing a PNG image, see the file example.c.
2747
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2748.SH V. Modifying/Customizing libpng:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2749
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]2750There are three issues here. The first is changing how libpng does
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2751standard things like memory allocation, input/output, and error handling.
2752The second deals with more complicated things like adding new chunks,
2753adding new transformations, and generally changing how libpng works.
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]2754Both of those are compile-time issues; that is, they are generally
2755determined at the time the code is written, and there is rarely a need
2756to provide the user with a means of changing them. The third is a
2757run-time issue: choosing between and/or tuning one or more alternate
2758versions of computationally intensive routines; specifically, optimized
2759assembly-language (and therefore compiler- and platform-dependent)
2760versions.
2761
2762Memory allocation, input/output, and error handling
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2763
2764All of the memory allocation, input/output, and error handling in libpng
Glenn Randers-Pehrson231e6872001-01-12 15:13:06 -0600[diff] [blame]2765goes through callbacks that are user-settable. The default routines are
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2766in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2767these functions, call the appropriate png_set_*_fn() function.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2768
Glenn Randers-Pehrsoncfbed9b2002-05-21 18:06:08 -0500[diff] [blame]2769Memory allocation is done through the functions png_malloc()
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2770and png_free(). These currently just call the standard C functions. If
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2771your pointers can't access more then 64K at a time, you will want to set
2772MAXSEG_64K in zlib.h. Since it is unlikely that the method of handling
2773memory allocation on a platform will change between applications, these
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2774functions must be modified in the library at compile time. If you prefer
2775to use a different method of allocating and freeing data, you can use
Glenn Randers-Pehrsoncfbed9b2002-05-21 18:06:08 -0500[diff] [blame]2776png_create_read_struct_2() or png_create_write_struct_2() to register
2777your own functions as described above.
Glenn Randers-Pehrsoncfbed9b2002-05-21 18:06:08 -0500[diff] [blame]2778These functions also provide a void pointer that can be retrieved via
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2779
2780 mem_ptr=png_get_mem_ptr(png_ptr);
2781
2782Your replacement memory functions must have prototypes as follows:
2783
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]2784 png_voidp malloc_fn(png_structp png_ptr,
Glenn Randers-Pehrsonae498dc2001-11-24 14:53:31 -0600[diff] [blame]2785 png_size_t size);
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2786 void free_fn(png_structp png_ptr, png_voidp ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2787
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]2788Your malloc_fn() must return NULL in case of failure. The png_malloc()
2789function will normally call png_error() if it receives a NULL from the
2790system memory allocator or from your replacement malloc_fn().
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]2791
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2792Input/Output in libpng is done through png_read() and png_write(),
2793which currently just call fread() and fwrite(). The FILE * is stored in
2794png_struct and is initialized via png_init_io(). If you wish to change
2795the method of I/O, the library supplies callbacks that you can set
2796through the function png_set_read_fn() and png_set_write_fn() at run
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2797time, instead of calling the png_init_io() function. These functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2798also provide a void pointer that can be retrieved via the function
2799png_get_io_ptr(). For example:
2800
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]2801 png_set_read_fn(png_structp read_ptr,
2802 voidp read_io_ptr, png_rw_ptr read_data_fn)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2803
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]2804 png_set_write_fn(png_structp write_ptr,
2805 voidp write_io_ptr, png_rw_ptr write_data_fn,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2806 png_flush_ptr output_flush_fn);
2807
Glenn Randers-Pehrsonf7d1a171998-06-06 15:31:35 -0500[diff] [blame]2808 voidp read_io_ptr = png_get_io_ptr(read_ptr);
2809 voidp write_io_ptr = png_get_io_ptr(write_ptr);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2810
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2811The replacement I/O functions must have prototypes as follows:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2812
2813 void user_read_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]2814 png_bytep data, png_size_t length);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2815 void user_write_data(png_structp png_ptr,
Glenn Randers-Pehrson837a3d12002-05-10 20:19:58 -0500[diff] [blame]2816 png_bytep data, png_size_t length);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2817 void user_flush_data(png_structp png_ptr);
2818
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]2819The user_read_data() function is responsible for detecting and
2820handling end-of-data errors.
2821
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2822Supplying NULL for the read, write, or flush functions sets them back
2823to using the default C stream functions. It is an error to read from
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2824a write stream, and vice versa.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2825
2826Error handling in libpng is done through png_error() and png_warning().
2827Errors handled through png_error() are fatal, meaning that png_error()
2828should never return to its caller. Currently, this is handled via
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2829setjmp() and longjmp() (unless you have compiled libpng with
2830PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
2831but you could change this to do things like exit() if you should wish.
2832
2833On non-fatal errors, png_warning() is called
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2834to print a warning message, and then control returns to the calling code.
2835By default png_error() and png_warning() print a message on stderr via
Glenn Randers-Pehrson38e6e772000-04-09 19:06:13 -0500[diff] [blame]2836fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
2837(because you don't want the messages) or PNG_NO_STDIO defined (because
2838fprintf() isn't available). If you wish to change the behavior of the error
2839functions, you will need to set up your own message callbacks. These
2840functions are normally supplied at the time that the png_struct is created.
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2841It is also possible to redirect errors and warnings to your own replacement
2842functions after png_create_*_struct() has been called by calling:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2843
2844 png_set_error_fn(png_structp png_ptr,
2845 png_voidp error_ptr, png_error_ptr error_fn,
2846 png_error_ptr warning_fn);
2847
2848 png_voidp error_ptr = png_get_error_ptr(png_ptr);
2849
2850If NULL is supplied for either error_fn or warning_fn, then the libpng
2851default function will be used, calling fprintf() and/or longjmp() if a
2852problem is encountered. The replacement error functions should have
2853parameters as follows:
2854
2855 void user_error_fn(png_structp png_ptr,
2856 png_const_charp error_msg);
2857 void user_warning_fn(png_structp png_ptr,
2858 png_const_charp warning_msg);
2859
2860The motivation behind using setjmp() and longjmp() is the C++ throw and
2861catch exception handling methods. This makes the code much easier to write,
2862as there is no need to check every return code of every function call.
2863However, there are some uncertainties about the status of local variables
2864after a longjmp, so the user may want to be careful about doing anything after
2865setjmp returns non-zero besides returning itself. Consult your compiler
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2866documentation for more details. For an alternative approach, you may wish
2867to use the "cexcept" facility (see http://cexcept.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2868
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2869.SS Custom chunks
2870
2871If you need to read or write custom chunks, you may need to get deeper
2872into the libpng code. The library now has mechanisms for storing
2873and writing chunks of unknown type; you can even declare callbacks
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]2874for custom chunks. However, this may not be good enough if the
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2875library code itself needs to know about interactions between your
2876chunk and existing `intrinsic' chunks.
2877
2878If you need to write a new intrinsic chunk, first read the PNG
2879specification. Acquire a first level of
2880understanding of how it works. Pay particular attention to the
2881sections that describe chunk names, and look at how other chunks were
2882designed, so you can do things similarly. Second, check out the
2883sections of libpng that read and write chunks. Try to find a chunk
2884that is similar to yours and use it as a template. More details can
2885be found in the comments inside the code. It is best to handle unknown
2886chunks in a generic method, via callback functions, instead of by
2887modifying libpng functions.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2888
2889If you wish to write your own transformation for the data, look through
2890the part of the code that does the transformations, and check out some of
2891the simpler ones to get an idea of how they work. Try to find a similar
2892transformation to the one you want to add and copy off of it. More details
2893can be found in the comments inside the code itself.
2894
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2895.SS Configuring for 16 bit platforms
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2896
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2897You 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]2898it 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]2899won'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]2900
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2901.SS Configuring for DOS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2902
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2903For DOS users who only have access to the lower 640K, you will
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2904have to limit zlib's memory usage via a png_set_compression_mem_level()
2905call. See zlib.h or zconf.h in the zlib library for more information.
2906
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2907.SS Configuring for Medium Model
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2908
2909Libpng's support for medium model has been tested on most of the popular
2910compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
2911defined, and FAR gets defined to far in pngconf.h, and you should be
2912all set. Everything in the library (except for zlib's structure) is
2913expecting far data. You must use the typedefs with the p or pp on
2914the end for pointers (or at least look at them and be careful). Make
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2915note that the rows of data are defined as png_bytepp, which is an
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2916unsigned char far * far *.
2917
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2918.SS Configuring for gui/windowing platforms:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2919
2920You will need to write new error and warning functions that use the GUI
2921interface, as described previously, and set them to be the error and
Glenn Randers-Pehrsona77ef622000-02-18 13:48:52 -0600[diff] [blame]2922warning functions at the time that png_create_*_struct() is called,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2923in order to have them available during the structure initialization.
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]2924They can be changed later via png_set_error_fn(). On some compilers,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2925you may also have to change the memory allocators (png_malloc, etc.).
2926
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2927.SS Configuring for compiler xxx:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2928
Glenn Randers-Pehrsonbeb572e2006-08-19 13:59:24 -0500[diff] [blame]2929All includes for libpng are in pngconf.h. If you need to add, change
2930or delete an include, this is the place to do it. The includes that
2931are not needed outside libpng are placed inside pngpriv.h, which is
2932only used by the routines inside libpng itself.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2933
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2934.SS Configuring zlib:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2935
2936There are special functions to configure the compression. Perhaps the
2937most useful one changes the compression level, which currently uses
2938input compression values in the range 0 - 9. The library normally
2939uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
2940have shown that for a large majority of images, compression values in
2941the range 3-6 compress nearly as well as higher levels, and do so much
2942faster. For online applications it may be desirable to have maximum speed
2943(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
2944specify no compression (Z_NO_COMPRESSION = 0), but this would create
2945files larger than just storing the raw bitmap. You can specify the
2946compression level by calling:
2947
2948 png_set_compression_level(png_ptr, level);
2949
2950Another useful one is to reduce the memory level used by the library.
2951The memory level defaults to 8, but it can be lowered if you are
2952short on memory (running DOS, for example, where you only have 640K).
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]2953Note that the memory level does have an effect on compression; among
2954other things, lower levels will result in sections of incompressible
2955data being emitted in smaller stored blocks, with a correspondingly
2956larger relative overhead of up to 15% in the worst case.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2957
2958 png_set_compression_mem_level(png_ptr, level);
2959
2960The other functions are for configuring zlib. They are not recommended
2961for normal use and may result in writing an invalid PNG file. See
2962zlib.h for more information on what these mean.
2963
2964 png_set_compression_strategy(png_ptr,
2965 strategy);
2966 png_set_compression_window_bits(png_ptr,
2967 window_bits);
2968 png_set_compression_method(png_ptr, method);
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]2969 png_set_compression_buffer_size(png_ptr, size);
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2970
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]2971.SS Controlling row filtering
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2972
2973If you want to control whether libpng uses filtering or not, which
2974filters are used, and how it goes about picking row filters, you
2975can call one of these functions. The selection and configuration
2976of row filters can have a significant impact on the size and
2977encoding speed and a somewhat lesser impact on the decoding speed
2978of an image. Filtering is enabled by default for RGB and grayscale
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]2979images (with and without alpha), but not for paletted images nor
2980for any images with bit depths less than 8 bits/pixel.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2981
2982The 'method' parameter sets the main filtering method, which is
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]2983currently only '0' in the PNG 1.2 specification. The 'filters'
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2984parameter sets which filter(s), if any, should be used for each
2985scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
2986to turn filtering on and off, respectively.
2987
2988Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
2989PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
Glenn Randers-Pehrson6942d532000-05-01 09:31:54 -0500[diff] [blame]2990ORed together with '|' to specify one or more filters to use.
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]2991These filters are described in more detail in the PNG specification.
2992If you intend to change the filter type during the course of writing
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2993the image, you should start with flags set for all of the filters
2994you intend to use so that libpng can initialize its internal
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]2995structures appropriately for all of the filter types. (Note that this
2996means the first row must always be adaptively filtered, because libpng
2997currently does not allocate the filter buffers until png_write_row()
2998is called for the first time.)
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]2999
3000 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3001 PNG_FILTER_UP | PNG_FILTER_AVE |
3002 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3003
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3004 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3005 filters);
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3006 The second parameter can also be
3007 PNG_INTRAPIXEL_DIFFERENCING if you are
3008 writing a PNG to be embedded in a MNG
3009 datastream. This parameter must be the
3010 same as the value of filter_method used
3011 in png_set_IHDR().
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3012
3013It is also possible to influence how libpng chooses from among the
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3014available filters. This is done in one or both of two ways - by
3015telling it how important it is to keep the same filter for successive
3016rows, and by telling it the relative computational costs of the filters.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3017
3018 double weights[3] = {1.5, 1.3, 1.1},
3019 costs[PNG_FILTER_VALUE_LAST] =
3020 {1.0, 1.3, 1.3, 1.5, 1.7};
3021
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3022 png_set_filter_heuristics(png_ptr,
3023 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3024 weights, costs);
3025
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3026The weights are multiplying factors that indicate to libpng that the
3027row filter should be the same for successive rows unless another row filter
3028is that many times better than the previous filter. In the above example,
3029if 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]3030"sum of absolute differences" 1.5 x 1.3 times higher than other filters
3031and still be chosen, while the NONE filter could have a sum 1.1 times
3032higher than other filters and still be chosen. Unspecified weights are
3033taken to be 1.0, and the specified weights should probably be declining
3034like those above in order to emphasize recent filters over older filters.
3035
3036The filter costs specify for each filter type a relative decoding cost
3037to be considered when selecting row filters. This means that filters
3038with higher costs are less likely to be chosen over filters with lower
3039costs, unless their "sum of absolute differences" is that much smaller.
3040The costs do not necessarily reflect the exact computational speeds of
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3041the various filters, since this would unduly influence the final image
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3042size.
3043
3044Note that the numbers above were invented purely for this example and
3045are given only to help explain the function usage. Little testing has
3046been done to find optimum values for either the costs or the weights.
3047
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3048.SS Removing unwanted object code
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3049
3050There are a bunch of #define's in pngconf.h that control what parts of
3051libpng are compiled. All the defines end in _SUPPORTED. If you are
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3052never going to use a capability, you can change the #define to #undef
3053before recompiling libpng and save yourself code and data space, or
3054you can turn off individual capabilities with defines that begin with
3055PNG_NO_.
3056
3057You can also turn all of the transforms and ancillary chunk capabilities
Glenn Randers-Pehrson228bd392000-04-23 23:14:02 -0500[diff] [blame]3058off en masse with compiler directives that define
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3059PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
3060or all four,
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3061along with directives to turn on any of the capabilities that you do
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3062want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3063the extra transformations but still leave the library fully capable of reading
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3064and writing PNG files with all known public chunks
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3065Use of the PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3066produces a library that is incapable of reading or writing ancillary chunks.
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3067If you are not using the progressive reading capability, you can
Glenn Randers-Pehrsond0dce401998-05-09 10:02:29 -0500[diff] [blame]3068turn that off with PNG_NO_PROGRESSIVE_READ (don't confuse
Glenn Randers-Pehrson08a33431998-03-07 06:06:55 -0600[diff] [blame]3069this with the INTERLACING capability, which you'll still have).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3070
3071All the reading and writing specific code are in separate files, so the
3072linker should only grab the files it needs. However, if you want to
3073make sure, or if you are building a stand alone library, all the
3074reading files start with pngr and all the writing files start with
3075pngw. The files that don't match either (like png.c, pngtrans.c, etc.)
3076are used for both reading and writing, and always need to be included.
3077The progressive reader is in pngpread.c
3078
3079If you are creating or distributing a dynamically linked library (a .so
3080or DLL file), you should not remove or disable any parts of the library,
3081as this will cause applications linked with different versions of the
3082library to fail if they call functions not available in your library.
3083The size of the library itself should not be an issue, because only
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3084those sections that are actually used will be loaded into memory.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3085
Glenn Randers-Pehrson61c32d92000-02-04 23:40:16 -0600[diff] [blame]3086.SS Requesting debug printout
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3087
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3088The macro definition PNG_DEBUG can be used to request debugging
3089printout. Set it to an integer value in the range 0 to 3. Higher
3090numbers result in increasing amounts of debugging information. The
3091information is printed to the "stderr" file, unless another file
3092name is specified in the PNG_DEBUG_FILE macro definition.
3093
3094When PNG_DEBUG > 0, the following functions (macros) become available:
3095
3096 png_debug(level, message)
3097 png_debug1(level, message, p1)
3098 png_debug2(level, message, p1, p2)
3099
3100in which "level" is compared to PNG_DEBUG to decide whether to print
3101the message, "message" is the formatted string to be printed,
3102and p1 and p2 are parameters that are to be embedded in the string
3103according to printf-style formatting directives. For example,
3104
3105 png_debug1(2, "foo=%d\n", foo);
3106
3107is expanded to
3108
3109 if(PNG_DEBUG > 2)
3110 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
3111
3112When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
3113can still use PNG_DEBUG to control your own debugging:
3114
3115 #ifdef PNG_DEBUG
3116 fprintf(stderr, ...
3117 #endif
3118
3119When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
3120having level = 0 will be printed. There aren't any such statements in
3121this version of libpng, but if you insert some they will be printed.
3122
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3123.SH VI. Runtime optimization
3124
3125A new feature in libpng 1.2.0 is the ability to dynamically switch between
3126standard and optimized versions of some routines. Currently these are
3127limited to three computationally intensive tasks when reading PNG files:
3128decoding row filters, expanding interlacing, and combining interlaced or
3129transparent row data with previous row data. Currently the optimized
3130versions are available only for x86 (Intel, AMD, etc.) platforms with
3131MMX support, though this may change in future versions. (For example,
3132the non-MMX assembler optimizations for zlib might become similarly
3133runtime-selectable in future releases, in which case libpng could be
3134extended to support them. Alternatively, the compile-time choice of
3135floating-point versus integer routines for gamma correction might become
3136runtime-selectable.)
3137
3138Because such optimizations tend to be very platform- and compiler-dependent,
3139both in how they are written and in how they perform, the new runtime code
3140in libpng has been written to allow programs to query, enable, and disable
3141either specific optimizations or all such optimizations. For example, to
3142enable all possible optimizations (bearing in mind that some "optimizations"
3143may actually run more slowly in rare cases):
3144
3145 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3146 png_uint_32 mask, flags;
3147
3148 flags = png_get_asm_flags(png_ptr);
3149 mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
3150 png_set_asm_flags(png_ptr, flags | mask);
3151 #endif
3152
3153To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ
3154by itself when calling png_get_asm_flagmask(); similarly for optimizing
3155only writing. To disable all optimizations:
3156
3157 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3158 flags = png_get_asm_flags(png_ptr);
3159 mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE);
3160 png_set_asm_flags(png_ptr, flags & ~mask);
3161 #endif
3162
3163To enable or disable only MMX-related features, use png_get_mmx_flagmask()
3164in place of png_get_asm_flagmask(). The mmx version takes one additional
3165parameter:
3166
3167 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3168 int selection = PNG_SELECT_READ | PNG_SELECT_WRITE;
3169 int compilerID;
3170
3171 mask = png_get_mmx_flagmask(selection, &compilerID);
3172 #endif
3173
3174On return, compilerID will indicate which version of the MMX assembler
3175optimizations was compiled. Currently two flavors exist: Microsoft
3176Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2).
3177On non-x86 platforms or on systems compiled without MMX optimizations, a
3178value of -1 is used.
3179
3180Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return
3181all valid, settable optimization bits for the version of the library that's
3182currently in use. In the case of shared (dynamically linked) libraries,
3183this may include optimizations that did not exist at the time the code was
3184written and compiled. It is also possible, of course, to enable only known,
3185specific optimizations; for example:
3186
3187 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3188 flags = PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
3189 | PNG_ASM_FLAG_MMX_READ_INTERLACE \
3190 | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
3191 | PNG_ASM_FLAG_MMX_READ_FILTER_UP \
3192 | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
3193 | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ;
3194 png_set_asm_flags(png_ptr, flags);
3195 #endif
3196
3197This method would enable only the MMX read-optimizations available at the
3198time of libpng 1.2.0's release, regardless of whether a later version of
3199the DLL were actually being used. (Also note that these functions did not
3200exist in versions older than 1.2.0, so any attempt to run a dynamically
3201linked app on such an older version would fail.)
3202
3203To determine whether the processor supports MMX instructions at all, use
3204the png_mmx_support() function:
3205
3206 #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200)
3207 mmxsupport = png_mmx_support();
3208 #endif
3209
3210It returns -1 if MMX support is not compiled into libpng, 0 if MMX code
3211is compiled but MMX is not supported by the processor, or 1 if MMX support
3212is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(),
3213and png_get_asm_flagmask() all may be called without allocating and ini-
3214tializing any PNG structures (for example, as part of a usage screen or
3215"about" box).
3216
3217The following code can be used to prevent an application from using the
3218thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK
3219defined:
3220
Glenn Randers-Pehrson17218292006-04-20 07:20:46 -0500[diff] [blame]3221#if defined(PNG_USE_PNGGCCRD) && defined(PNG_MMX_CODE_SUPPORTED) \
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3222 && defined(PNG_THREAD_UNSAFE_OK)
3223 /* Disable thread-unsafe features of pnggccrd */
Glenn Randers-Pehrson86dc9812006-05-10 07:27:44 -0500[diff] [blame]3224 if (png_access_version_number() >= 10200)
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3225 {
3226 png_uint_32 mmx_disable_mask = 0;
3227 png_uint_32 asm_flags;
3228
3229 mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \
3230 | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \
3231 | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \
3232 | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH );
3233 asm_flags = png_get_asm_flags(png_ptr);
3234 png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask);
3235 }
3236#endif
3237
3238For more extensive examples of runtime querying, enabling and disabling
3239of optimized features, see contrib/gregbook/readpng2.c in the libpng
3240source-code distribution.
3241
3242.SH VII. MNG support
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]3243
3244The MNG specification (available at http://www.libpng.org/pub/mng) allows
3245certain extensions to PNG for PNG images that are embedded in MNG datastreams.
3246Libpng can support some of these extensions. To enable them, use the
3247png_permit_mng_features() function:
3248
3249 feature_set = png_permit_mng_features(png_ptr, mask)
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3250 mask is a png_uint_32 containing the bitwise OR of the
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]3251 features you want to enable. These include
3252 PNG_FLAG_MNG_EMPTY_PLTE
3253 PNG_FLAG_MNG_FILTER_64
3254 PNG_ALL_MNG_FEATURES
Glenn Randers-Pehrsonebd7f9a2006-10-19 09:37:56 -0500[diff] [blame]3255 feature_set is a png_uint_32 that is the bitwise AND of
Glenn Randers-Pehrson2ad31ae2000-12-15 08:54:42 -0600[diff] [blame]3256 your mask with the set of MNG features that is
3257 supported by the version of libpng that you are using.
3258
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3259It is an error to use this function when reading or writing a standalone
3260PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
Glenn Randers-Pehrsonf05f8032000-12-23 14:27:39 -0600[diff] [blame]3261in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
3262and the MHDR and MEND chunks. Libpng does not provide support for these
3263or any other MNG chunks; your application must provide its own support for
3264them. You may wish to consider using libmng (available at
3265http://www.libmng.com) instead.
Glenn Randers-Pehrson408b4212000-12-18 09:33:57 -0600[diff] [blame]3266
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3267.SH VIII. Changes to Libpng from version 0.88
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3268
3269It should be noted that versions of libpng later than 0.96 are not
3270distributed by the original libpng author, Guy Schalnat, nor by
3271Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
3272distributed versions 0.89 through 0.96, but rather by another member
3273of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
3274still alive and well, but they have moved on to other things.
3275
3276The old libpng functions png_read_init(), png_write_init(),
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]3277png_info_init(), png_read_destroy(), and png_write_destroy() have been
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]3278moved to PNG_INTERNAL in version 0.95 to discourage their use. These
3279functions will be removed from libpng version 2.0.0.
3280
3281The preferred method of creating and initializing the libpng structures is
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3282via the png_create_read_struct(), png_create_write_struct(), and
3283png_create_info_struct() because they isolate the size of the structures
3284from the application, allow version error checking, and also allow the
3285use of custom error handling routines during the initialization, which
3286the old functions do not. The functions png_read_destroy() and
3287png_write_destroy() do not actually free the memory that libpng
3288allocated for these structs, but just reset the data structures, so they
3289can be used instead of png_destroy_read_struct() and
3290png_destroy_write_struct() if you feel there is too much system overhead
3291allocating and freeing the png_struct for each image read.
3292
3293Setting the error callbacks via png_set_message_fn() before
3294png_read_init() as was suggested in libpng-0.88 is no longer supported
Glenn Randers-Pehrson5c6aeb21998-12-29 11:47:59 -0600[diff] [blame]3295because this caused applications that do not use custom error functions
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3296to fail if the png_ptr was not initialized to zero. It is still possible
3297to set the error callbacks AFTER png_read_init(), or to change them with
Glenn Randers-Pehrson75294572000-05-06 14:09:57 -0500[diff] [blame]3298png_set_error_fn(), which is essentially the same function, but with a new
3299name to force compilation errors with applications that try to use the old
3300method.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3301
Glenn Randers-Pehrson1ef65b62000-05-12 06:19:53 -0500[diff] [blame]3302Starting with version 1.0.7, you can find out which version of the library
3303you are using at run-time:
3304
3305 png_uint_32 libpng_vn = png_access_version_number();
3306
3307The number libpng_vn is constructed from the major version, minor
3308version with leading zero, and release number with leading zero,
3309(e.g., libpng_vn for version 1.0.7 is 10007).
3310
3311You can also check which version of png.h you used when compiling your
3312application:
3313
3314 png_uint_32 application_vn = PNG_LIBPNG_VER;
3315
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3316.SH IX. Y2K Compliance in libpng
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3317
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3318May 15, 2007
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3319
3320Since the PNG Development group is an ad-hoc body, we can't make
3321an official declaration.
3322
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3323This is your unofficial assurance that libpng from version 0.71 and
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3324upward through 1.4.0beta19 are Y2K compliant. It is my belief that earlier
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3325versions were also Y2K compliant.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3326
3327Libpng only has three year fields. One is a 2-byte unsigned integer that
3328will hold years up to 65535. The other two hold the date in text
3329format, and will hold years up to 9999.
3330
3331The integer is
3332 "png_uint_16 year" in png_time_struct.
3333
3334The strings are
3335 "png_charp time_buffer" in png_struct and
3336 "near_time_buffer", which is a local character string in png.c.
3337
3338There are seven time-related functions:
3339
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3340 png_convert_to_rfc_1123() in png.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3341 (formerly png_convert_to_rfc_1152() in error)
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3342 png_convert_from_struct_tm() in pngwrite.c, called
3343 in pngwrite.c
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3344 png_convert_from_time_t() in pngwrite.c
3345 png_get_tIME() in pngget.c
3346 png_handle_tIME() in pngrutil.c, called in pngread.c
3347 png_set_tIME() in pngset.c
3348 png_write_tIME() in pngwutil.c, called in pngwrite.c
3349
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3350All appear to handle dates properly in a Y2K environment. The
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3351png_convert_from_time_t() function calls gmtime() to convert from system
3352clock time, which returns (year - 1900), which we properly convert to
3353the full 4-digit year. There is a possibility that applications using
3354libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3355function, or that they are incorrectly passing only a 2-digit year
3356instead of "year - 1900" into the png_convert_from_struct_tm() function,
3357but this is not under our control. The libpng documentation has always
3358stated that it works with 4-digit years, and the APIs have been
3359documented as such.
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3360
3361The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
3362integer to hold the year, and can hold years as large as 65535.
3363
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3364zlib, upon which libpng depends, is also Y2K compliant. It contains
3365no date-related code.
3366
Glenn Randers-Pehrson87544ac1999-01-13 22:06:39 -0600[diff] [blame]3367
3368 Glenn Randers-Pehrson
3369 libpng maintainer
3370 PNG Development Group
3371
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3372.SH NOTE
3373
3374Note about libpng version numbers:
3375
3376Due to various miscommunications, unforeseen code incompatibilities
3377and occasional factors outside the authors' control, version numbering
3378on the library has not always been consistent and straightforward.
3379The following table summarizes matters since version 0.89c, which was
3380the first widely used release:
3381
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3382 source png.h png.h shared-lib
3383 version string int version
3384 ------- ------ ----- ----------
3385 0.89c ("beta 3") 0.89 89 1.0.89
3386 0.90 ("beta 4") 0.90 90 0.90
3387 0.95 ("beta 5") 0.95 95 0.95
3388 0.96 ("beta 6") 0.96 96 0.96
3389 0.97b ("beta 7") 1.00.97 97 1.0.1
3390 0.97c 0.97 97 2.0.97
3391 0.98 0.98 98 2.0.98
3392 0.99 0.99 98 2.0.99
3393 0.99a-m 0.99 99 2.0.99
3394 1.00 1.00 100 2.1.0
3395 1.0.0 1.0.0 100 2.1.0
3396 1.0.0 (from here on, the 100 2.1.0
3397 1.0.1 png.h string is 10001 2.1.0
3398 1.0.1a-e identical to the 10002 from here on, the
3399 1.0.2 source version) 10002 shared library is 2.V
3400 1.0.2a-b 10003 where V is the source
3401 1.0.1 10001 code version except as
3402 1.0.1a-e 10002 2.1.0.1a-e noted.
3403 1.0.2 10002 2.1.0.2
3404 1.0.2a-b 10003 2.1.0.2a-b
3405 1.0.3 10003 2.1.0.3
3406 1.0.3a-d 10004 2.1.0.3a-d
3407 1.0.4 10004 2.1.0.4
3408 1.0.4a-f 10005 2.1.0.4a-f
3409 1.0.5 (+ 2 patches) 10005 2.1.0.5
3410 1.0.5a-d 10006 2.1.0.5a-d
3411 1.0.5e-r 10100 2.1.0.5e-r
3412 1.0.5s-v 10006 2.1.0.5s-v
3413 1.0.6 (+ 3 patches) 10006 2.1.0.6
3414 1.0.6d-g 10007 2.1.0.6d-g
3415 1.0.6h 10007 10.6h
3416 1.0.6i 10007 10.6i
3417 1.0.6j 10007 2.1.0.6j
3418 1.0.7beta11-14 DLLNUM 10007 2.1.0.7beta11-14
3419 1.0.7beta15-18 1 10007 2.1.0.7beta15-18
3420 1.0.7rc1-2 1 10007 2.1.0.7rc1-2
3421 1.0.7 1 10007 2.1.0.7
3422 1.0.8beta1-4 1 10008 2.1.0.8beta1-4
3423 1.0.8rc1 1 10008 2.1.0.8rc1
3424 1.0.8 1 10008 2.1.0.8
3425 1.0.9beta1-6 1 10009 2.1.0.9beta1-6
3426 1.0.9rc1 1 10009 2.1.0.9rc1
3427 1.0.9beta7-10 1 10009 2.1.0.9beta7-10
3428 1.0.9rc2 1 10009 2.1.0.9rc2
3429 1.0.9 1 10009 2.1.0.9
Glenn Randers-Pehrsone1644472001-03-23 05:06:56 -0600[diff] [blame]3430 1.0.10beta1 1 10010 2.1.0.10beta1
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3431 1.0.10rc1 1 10010 2.1.0.10rc1
Glenn Randers-Pehrson13cfbac2001-03-30 06:42:28 -0600[diff] [blame]3432 1.0.10 1 10010 2.1.0.10
Glenn Randers-Pehrsone1eff582001-04-14 20:15:41 -0500[diff] [blame]3433 1.0.11beta1-3 1 10011 2.1.0.11beta1-3
Glenn Randers-Pehrson82ae3832001-04-20 10:32:10 -0500[diff] [blame]3434 1.0.11rc1 1 10011 2.1.0.11rc1
Glenn Randers-Pehrson32835392001-04-27 08:29:32 -0500[diff] [blame]3435 1.0.11 1 10011 2.1.0.11
Glenn Randers-Pehrsonb1828932001-06-23 08:03:17 -0500[diff] [blame]3436 1.0.12beta1-2 2 10012 2.1.0.12beta1-2
3437 1.0.12rc1 2 10012 2.1.0.12rc1
3438 1.0.12 2 10012 2.1.0.12
3439 1.1.0a-f - 10100 2.1.1.0a-f abandoned
Glenn Randers-Pehrson8b6a8892001-05-18 04:54:50 -0500[diff] [blame]3440 1.2.0beta1-2 2 10200 2.1.2.0beta1-2
Glenn Randers-Pehrson5a0be342001-10-18 20:55:13 -0500[diff] [blame]3441 1.2.0beta3-5 3 10200 3.1.2.0beta3-5
3442 1.2.0rc1 3 10200 3.1.2.0rc1
3443 1.2.0 3 10200 3.1.2.0
Glenn Randers-Pehrson5cded0b2001-11-07 07:10:08 -0600[diff] [blame]3444 1.2.1beta-4 3 10201 3.1.2.1beta1-4
Glenn Randers-Pehrsondb3b88d2001-12-04 06:30:43 -0600[diff] [blame]3445 1.2.1rc1-2 3 10201 3.1.2.1rc1-2
3446 1.2.1 3 10201 3.1.2.1
Glenn Randers-Pehrson25228ab2002-03-31 07:33:55 -0600[diff] [blame]3447 1.2.2beta1-6 12 10202 12.so.0.1.2.2beta1-6
Glenn Randers-Pehrsonfcbd7872002-04-07 16:35:38 -0500[diff] [blame]3448 1.0.13beta1 10 10013 10.so.0.1.0.13beta1
3449 1.0.13rc1 10 10013 10.so.0.1.0.13rc1
3450 1.2.2rc1 12 10202 12.so.0.1.2.2rc1
Glenn Randers-Pehrson4fb046a2002-04-15 09:25:51 -0500[diff] [blame]3451 1.0.13 10 10013 10.so.0.1.0.13
3452 1.2.2 12 10202 12.so.0.1.2.2
Glenn Randers-Pehrson22f28962002-05-13 18:17:09 -0500[diff] [blame]3453 1.2.3rc1-6 12 10203 12.so.0.1.2.3rc1-6
3454 1.2.3 12 10203 12.so.0.1.2.3
Glenn Randers-Pehrsond020e9d2002-06-28 09:34:00 -0500[diff] [blame]3455 1.2.4beta1-3 13 10204 12.so.0.1.2.4beta1-3
Glenn Randers-Pehrson2ae022d2002-07-01 22:23:46 -0500[diff] [blame]3456 1.2.4rc1 13 10204 12.so.0.1.2.4rc1
Glenn Randers-Pehrson484a8a12002-07-07 19:15:20 -0500[diff] [blame]3457 1.0.14 10 10014 10.so.0.1.0.14
3458 1.2.4 13 10204 12.so.0.1.2.4
Glenn Randers-Pehrson5b5dcf82004-07-17 22:45:44 -0500[diff] [blame]3459 1.2.5beta1-2 13 10205 12.so.0.1.2.5beta1-2
3460 1.0.15rc1 10 10015 10.so.0.1.0.15rc1
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3461 1.0.15 10 10015 10.so.0.1.0.15
3462 1.2.5 13 10205 12.so.0.1.2.5
3463 1.2.6beta1-4 13 10206 12.so.0.1.2.6beta1-4
Glenn Randers-Pehrson37f116a2004-08-15 07:15:39 -0500[diff] [blame]3464 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5
3465 1.0.16 10 10016 10.so.0.1.0.16
3466 1.2.6 13 10206 12.so.0.1.2.6
Glenn Randers-Pehrson67864af2004-08-28 23:30:07 -0500[diff] [blame]3467 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2
Glenn Randers-Pehrson5b779162004-09-04 13:25:08 -0500[diff] [blame]3468 1.0.17rc1 10 10017 12.so.0.1.0.17rc1
3469 1.2.7rc1 13 10207 12.so.0.1.2.7rc1
Glenn Randers-Pehrson250dfe12004-09-11 21:19:54 -0500[diff] [blame]3470 1.0.17 10 10017 12.so.0.1.0.17
3471 1.2.7 13 10207 12.so.0.1.2.7
Glenn Randers-Pehrson40936072004-11-20 11:18:40 -0600[diff] [blame]3472 1.2.8beta1-5 13 10208 12.so.0.1.2.8beta1-5
Glenn Randers-Pehrson584b96e2004-11-29 15:08:00 -0600[diff] [blame]3473 1.0.18rc1-5 10 10018 12.so.0.1.0.18rc1-5
3474 1.2.8rc1-5 13 10208 12.so.0.1.2.8rc1-5
Glenn Randers-Pehrson917648e2004-12-02 18:14:51 -0600[diff] [blame]3475 1.0.18 10 10018 12.so.0.1.0.18
3476 1.2.8 13 10208 12.so.0.1.2.8
Glenn Randers-Pehrsone6474622006-03-04 16:50:47 -0600[diff] [blame]3477 1.2.9beta1-3 13 10209 12.so.0.1.2.9beta1-3
Glenn Randers-Pehrson4deeb792006-03-22 16:21:59 -0600[diff] [blame]3478 1.2.9beta4-11 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrson3a512032006-03-31 05:29:33 -0600[diff] [blame]3479 1.2.9rc1 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsona7d0c942006-04-14 06:22:52 -0500[diff] [blame]3480 1.2.9 13 10209 12.so.0.9[.0]
Glenn Randers-Pehrsond60b8fa2006-04-20 21:31:14 -0500[diff] [blame]3481 1.2.10beta1-7 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson17218292006-04-20 07:20:46 -0500[diff] [blame]3482 1.2.10rc1-2 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson86dc9812006-05-10 07:27:44 -0500[diff] [blame]3483 1.2.10 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson6bc53be2006-06-16 07:52:03 -0500[diff] [blame]3484 1.4.0beta1-6 14 10400 14.so.0.0[.0]
3485 1.2.11beta1-4 13 10210 12.so.0.10[.0]
Glenn Randers-Pehrson3424ee72006-07-12 13:33:47 -0500[diff] [blame]3486 1.4.0beta7-8 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrson701dbaa2006-11-17 09:36:54 -0600[diff] [blame]3487 1.2.11 13 10211 12.so.0.11[.0]
3488 1.2.12 13 10212 12.so.0.12[.0]
3489 1.4.0beta9-14 14 10400 14.so.0.0[.0]
3490 1.2.13 13 10213 12.so.0.13[.0]
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3491 1.4.0beta15-19 14 10400 14.so.0.0[.0]
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3492
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3493Henceforth the source version will match the shared-library minor
3494and patch numbers; the shared-library major version number will be
3495used for changes in backward compatibility, as it is intended. The
3496PNG_PNGLIB_VER macro, which is not used within libpng but is available
3497for applications, is an unsigned integer of the form xyyzz corresponding
3498to 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]3499were given the previous public release number plus a letter, until
3500version 1.0.6j; from then on they were given the upcoming public
3501release number plus "betaNN" or "rcN".
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3502
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3503.SH "SEE ALSO"
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3504libpngpf(3), png(5)
3505.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3506.IR libpng :
3507.IP
Glenn Randers-Pehrsona4981d42004-08-25 22:00:45 -0500[diff] [blame]3508http://libpng.sourceforge.net (follow the [DOWNLOAD] link)
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]3509http://www.libpng.org/pub/png
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3510
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3511.LP
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3512.IR zlib :
3513.IP
3514(generally) at the same location as
3515.I libpng
3516or at
3517.br
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]3518ftp://ftp.info-zip.org/pub/infozip/zlib
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3519
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3520.LP
3521.IR PNG specification: RFC 2083
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3522.IP
3523(generally) at the same location as
3524.I libpng
3525or at
3526.br
3527ftp://ds.internic.net/rfc/rfc2083.txt
3528.br
3529or (as a W3C Recommendation) at
3530.br
3531http://www.w3.org/TR/REC-png.html
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3532
Glenn Randers-Pehrsoncbe52d81998-02-28 07:00:24 -0600[diff] [blame]3533.LP
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3534In the case of any inconsistency between the PNG specification
3535and this library, the specification takes precedence.
3536
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3537.SH AUTHORS
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3538This man page: Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]3539<glennrp at users.sourceforge.net>
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3540
3541The contributing authors would like to thank all those who helped
3542with testing, bug fixes, and patience. This wouldn't have been
3543possible without all of you.
3544
3545Thanks to Frank J. T. Wojcik for helping with the documentation.
Glenn Randers-Pehrson166c5a31999-12-10 09:43:02 -0600[diff] [blame]3546
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3547Libpng version 1.4.0beta19 - May 15, 2007:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3548Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc.
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]3549Currently maintained by Glenn Randers-Pehrson (glennrp at users.sourceforge.net).
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3550
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3551Supported by the PNG development group
3552.br
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]3553png-mng-implement at lists.sf.net
3554(subscription required; visit
Glenn Randers-Pehrson7b34df32006-02-24 06:30:16 -0600[diff] [blame]3555png-mng-implement at lists.sourceforge.net (subscription required; visit
Glenn Randers-Pehrson9c3ab682006-02-20 22:09:05 -0600[diff] [blame]3556https://lists.sourceforge.net/lists/listinfo/png-mng-implement
3557to subscribe).
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3558
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3559.SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3560
Glenn Randers-Pehrson5e5c1e12000-11-10 12:26:19 -0600[diff] [blame]3561(This copy of the libpng notices is provided for your convenience. In case of
3562any discrepancy between this copy and the notices in the file png.h that is
3563included in the libpng distribution, the latter shall prevail.)
3564
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3565If you modify libpng you may insert additional notices immediately following
3566this sentence.
3567
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3568libpng versions 1.2.6, August 15, 2004, through 1.4.0beta19, May 15, 2007, are
3569Copyright (c) 2004,2006-2007 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3570distributed according to the same disclaimer and license as libpng-1.2.5
Glenn Randers-Pehrsond029a752004-08-09 21:50:32 -0500[diff] [blame]3571with the following individual added to the list of Contributing Authors
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3572
3573 Cosmin Truta
Glenn Randers-Pehrson5fea36f2004-07-28 08:20:44 -0500[diff] [blame]3574
3575libpng 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]3576Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are
Glenn Randers-Pehrson32fc5ce2000-07-24 06:34:14 -0500[diff] [blame]3577distributed according to the same disclaimer and license as libpng-1.0.6
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3578with the following individuals added to the list of Contributing Authors
3579
3580 Simon-Pierre Cadieux
3581 Eric S. Raymond
3582 Gilles Vollant
3583
3584and with the following additions to the disclaimer:
3585
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]3586 There is no warranty against interference with your
3587 enjoyment of the library or against infringement.
3588 There is no warranty that our efforts or the library
3589 will fulfill any of your particular purposes or needs.
3590 This library is provided with all faults, and the entire
3591 risk of satisfactory quality, performance, accuracy, and
3592 effort is with the user.
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3593
3594libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
3595Copyright (c) 1998, 1999 Glenn Randers-Pehrson
3596Distributed according to the same disclaimer and license as libpng-0.96,
3597with the following individuals added to the list of Contributing Authors:
3598
3599 Tom Lane
3600 Glenn Randers-Pehrson
3601 Willem van Schaik
3602
3603libpng versions 0.89, June 1996, through 0.96, May 1997, are
Glenn Randers-Pehrson54a066a1999-09-19 06:04:18 -0500[diff] [blame]3604Copyright (c) 1996, 1997 Andreas Dilger
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3605Distributed according to the same disclaimer and license as libpng-0.88,
3606with the following individuals added to the list of Contributing Authors:
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]3607
3608 John Bowler
3609 Kevin Bracey
3610 Sam Bushell
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]3611 Magnus Holmgren
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]3612 Greg Roelofs
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3613 Tom Tanner
3614
3615libpng versions 0.5, May 1995, through 0.88, January 1996, are
3616Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
3617
3618For the purposes of this copyright and license, "Contributing Authors"
3619is defined as the following set of individuals:
3620
3621 Andreas Dilger
3622 Dave Martindale
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]3623 Guy Eric Schalnat
3624 Paul Schmidt
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]3625 Tim Wegner
Glenn Randers-Pehrsonc9442291999-01-06 21:50:16 -0600[diff] [blame]3626
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3627The PNG Reference Library is supplied "AS IS". The Contributing Authors
3628and Group 42, Inc. disclaim all warranties, expressed or implied,
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3629including, without limitation, the warranties of merchantability and of
3630fitness for any purpose. The Contributing Authors and Group 42, Inc.
3631assume no liability for direct, indirect, incidental, special, exemplary,
3632or consequential damages, which may result from the use of the PNG
3633Reference Library, even if advised of the possibility of such damage.
Glenn Randers-Pehrsona357b991998-02-08 20:56:40 -0600[diff] [blame]3634
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3635Permission is hereby granted to use, copy, modify, and distribute this
3636source code, or portions hereof, for any purpose, without fee, subject
3637to the following restrictions:
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3638
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]36391. The origin of this source code must not be misrepresented.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3640
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]36412. Altered versions must be plainly marked as such and
3642 must not be misrepresented as being the original source.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3643
Glenn Randers-Pehrson19095602001-03-14 07:08:39 -0600[diff] [blame]36443. This Copyright notice may not be removed or altered from
3645 any source or altered source distribution.
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3646
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3647The Contributing Authors and Group 42, Inc. specifically permit, without
3648fee, and encourage the use of this source code as a component to
3649supporting the PNG file format in commercial products. If you use this
3650source code in a product, acknowledgment is not required but would be
3651appreciated.
3652
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3653
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3654A "png_get_copyright" function is available, for convenient use in "about"
3655boxes and the like:
3656
3657 printf("%s",png_get_copyright(NULL));
3658
3659Also, the PNG logo (in PNG format, of course) is supplied in the
Glenn Randers-Pehrsona4d54bd2000-07-14 08:15:12 -0500[diff] [blame]3660files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
Glenn Randers-Pehrson4393a9a1999-09-17 12:27:26 -0500[diff] [blame]3661
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3662Libpng is OSI Certified Open Source Software. OSI Certified Open Source is a
Glenn Randers-Pehrsonbcfd15d1999-10-01 14:22:25 -0500[diff] [blame]3663certification mark of the Open Source Initiative.
3664
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3665Glenn Randers-Pehrson
Glenn Randers-Pehrson5dd2b8e2004-11-24 07:50:16 -0600[diff] [blame]3666glennrp at users.sourceforge.net
Glenn Randers-Pehrsona7dbcba2007-05-15 16:16:34 -0500[diff] [blame^]3667May 15, 2007
Glenn Randers-Pehrson3d5a5202000-07-01 15:37:28 -0500[diff] [blame]3668
Glenn Randers-Pehrson0f881d61998-02-07 10:20:57 -0600[diff] [blame]3669.\" end of man page
3670