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