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