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