png.h 145.3 KB
Newer Older
1

A
Andreas Dilger 已提交
2
/* png.h - header file for PNG reference library
3
 *
4
 * libpng version 1.6.5beta01 - September 12, 2013
5
 * Copyright (c) 1998-2013 Glenn Randers-Pehrson
6 7
 * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
 * (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
8
 *
9
 * This code is released under the libpng license (See LICENSE, below)
10
 *
11
 * Authors and maintainers:
12 13
 *   libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
 *   libpng versions 0.89c, June 1996, through 0.96, May 1997: Andreas Dilger
14
 *   libpng versions 0.97, January 1998, through 1.6.5beta01 - September 12, 2013: Glenn
15
 *   See also "Contributing Authors", below.
16
 *
17
 * Note about libpng version numbers:
18
 *
19 20 21 22 23
 *   Due to various miscommunications, unforeseen code incompatibilities
 *   and occasional factors outside the authors' control, version numbering
 *   on the library has not always been consistent and straightforward.
 *   The following table summarizes matters since version 0.89c, which was
 *   the first widely used release:
24
 *
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
 *    source                 png.h  png.h  shared-lib
 *    version                string   int  version
 *    -------                ------ -----  ----------
 *    0.89c "1.0 beta 3"     0.89      89  1.0.89
 *    0.90  "1.0 beta 4"     0.90      90  0.90  [should have been 2.0.90]
 *    0.95  "1.0 beta 5"     0.95      95  0.95  [should have been 2.0.95]
 *    0.96  "1.0 beta 6"     0.96      96  0.96  [should have been 2.0.96]
 *    0.97b "1.00.97 beta 7" 1.00.97   97  1.0.1 [should have been 2.0.97]
 *    0.97c                  0.97      97  2.0.97
 *    0.98                   0.98      98  2.0.98
 *    0.99                   0.99      98  2.0.99
 *    0.99a-m                0.99      99  2.0.99
 *    1.00                   1.00     100  2.1.0 [100 should be 10000]
 *    1.0.0      (from here on, the   100  2.1.0 [100 should be 10000]
 *    1.0.1       png.h string is   10001  2.1.0
 *    1.0.1a-e    identical to the  10002  from here on, the shared library
 *    1.0.2       source version)   10002  is 2.V where V is the source code
 *    1.0.2a-b                      10003  version, except as noted.
 *    1.0.3                         10003
 *    1.0.3a-d                      10004
 *    1.0.4                         10004
 *    1.0.4a-f                      10005
 *    1.0.5 (+ 2 patches)           10005
 *    1.0.5a-d                      10006
 *    1.0.5e-r                      10100 (not source compatible)
 *    1.0.5s-v                      10006 (not binary compatible)
 *    1.0.6 (+ 3 patches)           10006 (still binary incompatible)
 *    1.0.6d-f                      10007 (still binary incompatible)
 *    1.0.6g                        10007
 *    1.0.6h                        10007  10.6h (testing xy.z so-numbering)
 *    1.0.6i                        10007  10.6i
 *    1.0.6j                        10007  2.1.0.6j (incompatible with 1.0.0)
57 58 59 60 61 62 63 64 65 66 67
 *    1.0.7beta11-14        DLLNUM  10007  2.1.0.7beta11-14 (binary compatible)
 *    1.0.7beta15-18           1    10007  2.1.0.7beta15-18 (binary compatible)
 *    1.0.7rc1-2               1    10007  2.1.0.7rc1-2 (binary compatible)
 *    1.0.7                    1    10007  (still compatible)
 *    1.0.8beta1-4             1    10008  2.1.0.8beta1-4
 *    1.0.8rc1                 1    10008  2.1.0.8rc1
 *    1.0.8                    1    10008  2.1.0.8
 *    1.0.9beta1-6             1    10009  2.1.0.9beta1-6
 *    1.0.9rc1                 1    10009  2.1.0.9rc1
 *    1.0.9beta7-10            1    10009  2.1.0.9beta7-10
 *    1.0.9rc2                 1    10009  2.1.0.9rc2
68
 *    1.0.9                    1    10009  2.1.0.9
69
 *    1.0.10beta1              1    10010  2.1.0.10beta1
70
 *    1.0.10rc1                1    10010  2.1.0.10rc1
71
 *    1.0.10                   1    10010  2.1.0.10
72
 *    1.0.11beta1-3            1    10011  2.1.0.11beta1-3
73
 *    1.0.11rc1                1    10011  2.1.0.11rc1
74
 *    1.0.11                   1    10011  2.1.0.11
75 76 77 78
 *    1.0.12beta1-2            2    10012  2.1.0.12beta1-2
 *    1.0.12rc1                2    10012  2.1.0.12rc1
 *    1.0.12                   2    10012  2.1.0.12
 *    1.1.0a-f                 -    10100  2.1.1.0a-f (branch abandoned)
79
 *    1.2.0beta1-2             2    10200  2.1.2.0beta1-2
80 81 82
 *    1.2.0beta3-5             3    10200  3.1.2.0beta3-5
 *    1.2.0rc1                 3    10200  3.1.2.0rc1
 *    1.2.0                    3    10200  3.1.2.0
83
 *    1.2.1beta1-4             3    10201  3.1.2.1beta1-4
84 85
 *    1.2.1rc1-2               3    10201  3.1.2.1rc1-2
 *    1.2.1                    3    10201  3.1.2.1
86
 *    1.2.2beta1-6            12    10202  12.so.0.1.2.2beta1-6
87 88 89
 *    1.0.13beta1             10    10013  10.so.0.1.0.13beta1
 *    1.0.13rc1               10    10013  10.so.0.1.0.13rc1
 *    1.2.2rc1                12    10202  12.so.0.1.2.2rc1
90 91
 *    1.0.13                  10    10013  10.so.0.1.0.13
 *    1.2.2                   12    10202  12.so.0.1.2.2
92 93
 *    1.2.3rc1-6              12    10203  12.so.0.1.2.3rc1-6
 *    1.2.3                   12    10203  12.so.0.1.2.3
94
 *    1.2.4beta1-3            13    10204  12.so.0.1.2.4beta1-3
95 96
 *    1.0.14rc1               13    10014  10.so.0.1.0.14rc1
 *    1.2.4rc1                13    10204  12.so.0.1.2.4rc1
97 98
 *    1.0.14                  10    10014  10.so.0.1.0.14
 *    1.2.4                   13    10204  12.so.0.1.2.4
99
 *    1.2.5beta1-2            13    10205  12.so.0.1.2.5beta1-2
100
 *    1.0.15rc1-3             10    10015  10.so.0.1.0.15rc1-3
101 102 103
 *    1.2.5rc1-3              13    10205  12.so.0.1.2.5rc1-3
 *    1.0.15                  10    10015  10.so.0.1.0.15
 *    1.2.5                   13    10205  12.so.0.1.2.5
104
 *    1.2.6beta1-4            13    10206  12.so.0.1.2.6beta1-4
105 106
 *    1.0.16                  10    10016  10.so.0.1.0.16
 *    1.2.6                   13    10206  12.so.0.1.2.6
107
 *    1.2.7beta1-2            13    10207  12.so.0.1.2.7beta1-2
108 109
 *    1.0.17rc1               10    10017  12.so.0.1.0.17rc1
 *    1.2.7rc1                13    10207  12.so.0.1.2.7rc1
110 111
 *    1.0.17                  10    10017  12.so.0.1.0.17
 *    1.2.7                   13    10207  12.so.0.1.2.7
112
 *    1.2.8beta1-5            13    10208  12.so.0.1.2.8beta1-5
113 114
 *    1.0.18rc1-5             10    10018  12.so.0.1.0.18rc1-5
 *    1.2.8rc1-5              13    10208  12.so.0.1.2.8rc1-5
115 116
 *    1.0.18                  10    10018  12.so.0.1.0.18
 *    1.2.8                   13    10208  12.so.0.1.2.8
117
 *    1.2.9beta1-3            13    10209  12.so.0.1.2.9beta1-3
118
 *    1.2.9beta4-11           13    10209  12.so.0.9[.0]
119
 *    1.2.9rc1                13    10209  12.so.0.9[.0]
120
 *    1.2.9                   13    10209  12.so.0.9[.0]
121
 *    1.2.10beta1-7           13    10210  12.so.0.10[.0]
122
 *    1.2.10rc1-2             13    10210  12.so.0.10[.0]
123
 *    1.2.10                  13    10210  12.so.0.10[.0]
124
 *    1.4.0beta1-5            14    10400  14.so.0.0[.0]
125
 *    1.2.11beta1-4           13    10211  12.so.0.11[.0]
126
 *    1.4.0beta7-8            14    10400  14.so.0.0[.0]
127 128
 *    1.2.11                  13    10211  12.so.0.11[.0]
 *    1.2.12                  13    10212  12.so.0.12[.0]
129
 *    1.4.0beta9-14           14    10400  14.so.0.0[.0]
130
 *    1.2.13                  13    10213  12.so.0.13[.0]
131
 *    1.4.0beta15-36          14    10400  14.so.0.0[.0]
132
 *    1.4.0beta37-87          14    10400  14.so.14.0[.0]
133
 *    1.4.0rc01               14    10400  14.so.14.0[.0]
134
 *    1.4.0beta88-109         14    10400  14.so.14.0[.0]
135
 *    1.4.0rc02-08            14    10400  14.so.14.0[.0]
136
 *    1.4.0                   14    10400  14.so.14.0[.0]
137 138
 *    1.4.1beta01-03          14    10401  14.so.14.1[.0]
 *    1.4.1rc01               14    10401  14.so.14.1[.0]
139
 *    1.4.1beta04-12          14    10401  14.so.14.1[.0]
140
 *    1.4.1                   14    10401  14.so.14.1[.0]
141 142
 *    1.4.2                   14    10402  14.so.14.2[.0]
 *    1.4.3                   14    10403  14.so.14.3[.0]
143
 *    1.4.4                   14    10404  14.so.14.4[.0]
144
 *    1.5.0beta01-58          15    10500  15.so.15.0[.0]
145
 *    1.5.0rc01-07            15    10500  15.so.15.0[.0]
146
 *    1.5.0                   15    10500  15.so.15.0[.0]
147
 *    1.5.1beta01-11          15    10501  15.so.15.1[.0]
148 149
 *    1.5.1rc01-02            15    10501  15.so.15.1[.0]
 *    1.5.1                   15    10501  15.so.15.1[.0]
150
 *    1.5.2beta01-03          15    10502  15.so.15.2[.0]
151
 *    1.5.2rc01-03            15    10502  15.so.15.2[.0]
152
 *    1.5.2                   15    10502  15.so.15.2[.0]
153
 *    1.5.3beta01-10          15    10503  15.so.15.3[.0]
154
 *    1.5.3rc01-02            15    10503  15.so.15.3[.0]
155 156
 *    1.5.3beta11             15    10503  15.so.15.3[.0]
 *    1.5.3 [omitted]
157
 *    1.5.4beta01-08          15    10504  15.so.15.4[.0]
158
 *    1.5.4rc01               15    10504  15.so.15.4[.0]
159
 *    1.5.4                   15    10504  15.so.15.4[.0]
160 161
 *    1.5.5beta01-08          15    10505  15.so.15.5[.0]
 *    1.5.5rc01               15    10505  15.so.15.5[.0]
162
 *    1.5.5                   15    10505  15.so.15.5[.0]
163
 *    1.5.6beta01-07          15    10506  15.so.15.6[.0]
164 165
 *    1.5.6rc01-03            15    10506  15.so.15.6[.0]
 *    1.5.6                   15    10506  15.so.15.6[.0]
166
 *    1.5.7beta01-05          15    10507  15.so.15.7[.0]
167 168
 *    1.5.7rc01-03            15    10507  15.so.15.7[.0]
 *    1.5.7                   15    10507  15.so.15.7[.0]
169 170 171
 *    1.6.0beta01-40          16    10600  16.so.16.0[.0]
 *    1.6.0rc01-08            16    10600  16.so.16.0[.0]
 *    1.6.0                   16    10600  16.so.16.0[.0]
172
 *    1.6.1beta01-09          16    10601  16.so.16.1[.0]
173
 *    1.6.1rc01               16    10601  16.so.16.1[.0]
174
 *    1.6.1                   16    10601  16.so.16.1[.0]
175
 *    1.6.2beta01             16    10602  16.so.16.2[.0]
176
 *    1.6.2rc01-06            16    10602  16.so.16.2[.0]
177
 *    1.6.2                   16    10602  16.so.16.2[.0]
178 179
 *    1.6.3beta01-11          16    10603  16.so.16.3[.0]
 *    1.6.3rc01               16    10603  16.so.16.3[.0]
180
 *    1.6.3                   16    10603  16.so.16.3[.0]
181 182
 *    1.6.4beta01-02          16    10604  16.so.16.4[.0]
 *    1.6.4rc01               16    10604  16.so.16.4[.0]
183
 *    1.6.4                   16    10604  16.so.16.4[.0]
184
 *
185 186 187 188 189 190 191 192
 *   Henceforth the source version will match the shared-library major
 *   and minor numbers; the shared-library major version number will be
 *   used for changes in backward compatibility, as it is intended.  The
 *   PNG_LIBPNG_VER macro, which is not used within libpng but is available
 *   for applications, is an unsigned integer of the form xyyzz corresponding
 *   to the source version x.y.z (leading zeros in y and z).  Beta versions
 *   were given the previous public release number plus a letter, until
 *   version 1.0.6j; from then on they were given the upcoming public
193
 *   release number plus "betaNN" or "rcNN".
194
 *
195 196 197
 *   Binary incompatibility exists only when applications make direct access
 *   to the info_ptr or png_ptr members through png.h, and the compiled
 *   application is loaded with a different version of the library.
198
 *
199 200
 *   DLLNUM will change each time there are forward or backward changes
 *   in binary compatibility (e.g., when a new feature is added).
201
 *
202 203 204
 * See libpng-manual.txt or libpng.3 for more information.  The PNG
 * specification is available as a W3C Recommendation and as an ISO
 * Specification, <http://www.w3.org/TR/2003/REC-PNG-20031110/
205 206 207
 */

/*
208 209
 * COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
 *
210 211
 * If you modify libpng you may insert additional notices immediately following
 * this sentence.
212
 *
213 214
 * This code is released under the libpng license.
 *
215
 * libpng versions 1.2.6, August 15, 2004, through 1.6.5beta01, September 12, 2013, are
216
 * Copyright (c) 2004, 2006-2013 Glenn Randers-Pehrson, and are
217
 * distributed according to the same disclaimer and license as libpng-1.2.5
218
 * with the following individual added to the list of Contributing Authors:
219 220 221
 *
 *    Cosmin Truta
 *
222
 * libpng versions 1.0.7, July 1, 2000, through 1.2.5, October 3, 2002, are
223
 * Copyright (c) 2000-2002 Glenn Randers-Pehrson, and are
224
 * distributed according to the same disclaimer and license as libpng-1.0.6
225
 * with the following individuals added to the list of Contributing Authors:
226
 *
227 228 229 230
 *    Simon-Pierre Cadieux
 *    Eric S. Raymond
 *    Gilles Vollant
 *
231 232 233 234 235 236 237 238 239 240
 * and with the following additions to the disclaimer:
 *
 *    There is no warranty against interference with your enjoyment of the
 *    library or against infringement.  There is no warranty that our
 *    efforts or the library will fulfill any of your particular purposes
 *    or needs.  This library is provided with all faults, and the entire
 *    risk of satisfactory quality, performance, accuracy, and effort is with
 *    the user.
 *
 * libpng versions 0.97, January 1998, through 1.0.6, March 20, 2000, are
241
 * Copyright (c) 1998, 1999, 2000 Glenn Randers-Pehrson, and are
242
 * distributed according to the same disclaimer and license as libpng-0.96,
243 244 245 246 247 248 249 250
 * with the following individuals added to the list of Contributing Authors:
 *
 *    Tom Lane
 *    Glenn Randers-Pehrson
 *    Willem van Schaik
 *
 * libpng versions 0.89, June 1996, through 0.96, May 1997, are
 * Copyright (c) 1996, 1997 Andreas Dilger
251
 * Distributed according to the same disclaimer and license as libpng-0.88,
252
 * with the following individuals added to the list of Contributing Authors:
253
 *
254 255
 *    John Bowler
 *    Kevin Bracey
256
 *    Sam Bushell
257 258
 *    Magnus Holmgren
 *    Greg Roelofs
259 260 261 262 263 264 265 266 267 268
 *    Tom Tanner
 *
 * libpng versions 0.5, May 1995, through 0.88, January 1996, are
 * Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
 *
 * For the purposes of this copyright and license, "Contributing Authors"
 * is defined as the following set of individuals:
 *
 *    Andreas Dilger
 *    Dave Martindale
269 270 271 272 273
 *    Guy Eric Schalnat
 *    Paul Schmidt
 *    Tim Wegner
 *
 * The PNG Reference Library is supplied "AS IS".  The Contributing Authors
274
 * and Group 42, Inc. disclaim all warranties, expressed or implied,
275 276
 * including, without limitation, the warranties of merchantability and of
 * fitness for any purpose.  The Contributing Authors and Group 42, Inc.
277
 * assume no liability for direct, indirect, incidental, special, exemplary,
278 279 280 281 282 283
 * or consequential damages, which may result from the use of the PNG
 * Reference Library, even if advised of the possibility of such damage.
 *
 * Permission is hereby granted to use, copy, modify, and distribute this
 * source code, or portions hereof, for any purpose, without fee, subject
 * to the following restrictions:
284
 *
285
 *   1. The origin of this source code must not be misrepresented.
286
 *
287 288
 *   2. Altered versions must be plainly marked as such and must not
 *      be misrepresented as being the original source.
289
 *
290 291
 *   3. This Copyright notice may not be removed or altered from
 *      any source or altered source distribution.
292 293 294 295 296 297 298
 *
 * The Contributing Authors and Group 42, Inc. specifically permit, without
 * fee, and encourage the use of this source code as a component to
 * supporting the PNG file format in commercial products.  If you use this
 * source code in a product, acknowledgment is not required but would be
 * appreciated.
 */
G
Guy Schalnat 已提交
299

300
/*
301 302
 * A "png_get_copyright" function is available, for convenient use in "about"
 * boxes and the like:
303
 *
304
 *     printf("%s", png_get_copyright(NULL));
305
 *
306
 * Also, the PNG logo (in PNG format, of course) is supplied in the
307
 * files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
308 309 310
 */

/*
311 312 313 314 315 316 317 318 319 320 321 322
 * Libpng is OSI Certified Open Source Software.  OSI Certified is a
 * certification mark of the Open Source Initiative.
 */

/*
 * The contributing authors would like to thank all those who helped
 * with testing, bug fixes, and patience.  This wouldn't have been
 * possible without all of you.
 *
 * Thanks to Frank J. T. Wojcik for helping with the documentation.
 */

323 324 325 326
/*
 * Y2K compliance in libpng:
 * =========================
 *
327
 *    September 12, 2013
328 329 330 331 332
 *
 *    Since the PNG Development group is an ad-hoc body, we can't make
 *    an official declaration.
 *
 *    This is your unofficial assurance that libpng from version 0.71 and
333
 *    upward through 1.6.5beta01 are Y2K compliant.  It is my belief that
G
[devel]  
Glenn Randers-Pehrson 已提交
334
 *    earlier versions were also Y2K compliant.
335
 *
336
 *    Libpng only has two year fields.  One is a 2-byte unsigned integer
337 338
 *    that will hold years up to 65535.  The other, which is deprecated,
 *    holds the date in text format, and will hold years up to 9999.
339 340 341 342
 *
 *    The integer is
 *        "png_uint_16 year" in png_time_struct.
 *
343
 *    The string is
344 345
 *        "char time_buffer[29]" in png_struct.  This is no longer used
 *    in libpng-1.6.x and will be removed from libpng-1.7.0.
346 347
 *
 *    There are seven time-related functions:
348 349 350
 *        png.c: png_convert_to_rfc_1123_buffer() in png.c
 *          (formerly png_convert_to_rfc_1123() prior to libpng-1.5.x and
 *          png_convert_to_rfc_1152() in error prior to libpng-0.98)
351 352 353 354 355 356 357 358 359 360
 *        png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c
 *        png_convert_from_time_t() in pngwrite.c
 *        png_get_tIME() in pngget.c
 *        png_handle_tIME() in pngrutil.c, called in pngread.c
 *        png_set_tIME() in pngset.c
 *        png_write_tIME() in pngwutil.c, called in pngwrite.c
 *
 *    All handle dates properly in a Y2K environment.  The
 *    png_convert_from_time_t() function calls gmtime() to convert from system
 *    clock time, which returns (year - 1900), which we properly convert to
361 362
 *    the full 4-digit year.  There is a possibility that libpng applications
 *    are not passing 4-digit years into the png_convert_to_rfc_1123_buffer()
363
 *    function, or that they are incorrectly passing only a 2-digit year
364
 *    instead of "year - 1900" into the png_convert_from_struct_tm() function,
365 366 367 368 369 370 371 372 373 374 375 376 377 378 379
 *    but this is not under our control.  The libpng documentation has always
 *    stated that it works with 4-digit years, and the APIs have been
 *    documented as such.
 *
 *    The tIME chunk itself is also Y2K compliant.  It uses a 2-byte unsigned
 *    integer to hold the year, and can hold years as large as 65535.
 *
 *    zlib, upon which libpng depends, is also Y2K compliant.  It contains
 *    no date-related code.
 *
 *       Glenn Randers-Pehrson
 *       libpng maintainer
 *       PNG Development Group
 */

380 381
#ifndef PNG_H
#define PNG_H
G
Guy Schalnat 已提交
382

383
/* This is not the place to learn how to use libpng. The file libpng-manual.txt
A
Andreas Dilger 已提交
384 385 386
 * describes how to use libpng, and the file example.c summarizes it
 * with some code on which to build.  This file is useful for looking
 * at the actual function definitions and structure components.
387 388 389
 *
 * If you just need to read a PNG file and don't want to read the documentation
 * skip to the end of this file and read the section entitled 'simplified API'.
A
Andreas Dilger 已提交
390
 */
G
Guy Schalnat 已提交
391

392
/* Version information for png.h - this should match the version in png.c */
393
#define PNG_LIBPNG_VER_STRING "1.6.5beta01"
394
#define PNG_HEADER_VERSION_STRING \
395
     " libpng version 1.6.5beta01 - September 12, 2013\n"
396

397 398
#define PNG_LIBPNG_VER_SONUM   16
#define PNG_LIBPNG_VER_DLLNUM  16
399 400 401

/* These should match the first 3 components of PNG_LIBPNG_VER_STRING: */
#define PNG_LIBPNG_VER_MAJOR   1
402
#define PNG_LIBPNG_VER_MINOR   6
403
#define PNG_LIBPNG_VER_RELEASE 5
404

405
/* This should match the numeric part of the final component of
406 407
 * PNG_LIBPNG_VER_STRING, omitting any leading zero:
 */
408

409
#define PNG_LIBPNG_VER_BUILD  01
410

411
/* Release Status */
412 413 414 415
#define PNG_LIBPNG_BUILD_ALPHA    1
#define PNG_LIBPNG_BUILD_BETA     2
#define PNG_LIBPNG_BUILD_RC       3
#define PNG_LIBPNG_BUILD_STABLE   4
416
#define PNG_LIBPNG_BUILD_RELEASE_STATUS_MASK 7
417

418 419 420 421 422 423 424
/* Release-Specific Flags */
#define PNG_LIBPNG_BUILD_PATCH    8 /* Can be OR'ed with
                                       PNG_LIBPNG_BUILD_STABLE only */
#define PNG_LIBPNG_BUILD_PRIVATE 16 /* Cannot be OR'ed with
                                       PNG_LIBPNG_BUILD_SPECIAL */
#define PNG_LIBPNG_BUILD_SPECIAL 32 /* Cannot be OR'ed with
                                       PNG_LIBPNG_BUILD_PRIVATE */
425

426
#define PNG_LIBPNG_BUILD_BASE_TYPE PNG_LIBPNG_BUILD_BETA
427

428 429 430 431
/* Careful here.  At one time, Guy wanted to use 082, but that would be octal.
 * We must not include leading zeros.
 * Versions 0.7 through 1.0.0 were in the range 0 to 100 here (only
 * version 1.0.0 was mis-numbered 100 instead of 10000).  From
432 433
 * version 1.0.1 it's    xxyyzz, where x=major, y=minor, z=release
 */
434
#define PNG_LIBPNG_VER 10605 /* 1.6.5 */
435

436 437 438 439
/* Library configuration: these options cannot be changed after
 * the library has been built.
 */
#ifndef PNGLCONF_H
440 441 442
    /* If pnglibconf.h is missing, you can
     * copy scripts/pnglibconf.h.prebuilt to pnglibconf.h
     */
443
#   include "pnglibconf.h"
444 445
#endif

446
#ifndef PNG_VERSION_INFO_ONLY
447
   /* Machine specific configuration. */
448 449
#  include "pngconf.h"
#endif
G
Guy Schalnat 已提交
450

451
/*
452 453 454
 * Added at libpng-1.2.8
 *
 * Ref MSDN: Private as priority over Special
455 456
 * VS_FF_PRIVATEBUILD File *was not* built using standard release
 * procedures. If this value is given, the StringFileInfo block must
457
 * contain a PrivateBuild string.
458 459 460 461
 *
 * VS_FF_SPECIALBUILD File *was* built by the original company using
 * standard release procedures but is a variation of the standard
 * file of the same version number. If this value is given, the
462
 * StringFileInfo block must contain a SpecialBuild string.
463 464
 */

465
#ifdef PNG_USER_PRIVATEBUILD /* From pnglibconf.h */
466
#  define PNG_LIBPNG_BUILD_TYPE \
467
       (PNG_LIBPNG_BUILD_BASE_TYPE | PNG_LIBPNG_BUILD_PRIVATE)
468
#else
469
#  ifdef PNG_LIBPNG_SPECIALBUILD
470
#    define PNG_LIBPNG_BUILD_TYPE \
471
         (PNG_LIBPNG_BUILD_BASE_TYPE | PNG_LIBPNG_BUILD_SPECIAL)
472
#  else
473
#    define PNG_LIBPNG_BUILD_TYPE (PNG_LIBPNG_BUILD_BASE_TYPE)
474 475 476 477 478
#  endif
#endif

#ifndef PNG_VERSION_INFO_ONLY

479 480 481 482 483
/* Inhibit C++ name-mangling for libpng functions but not for system calls. */
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

A
Andreas Dilger 已提交
484 485 486
/* Version information for C files, stored in png.c.  This had better match
 * the version above.
 */
487
#define png_libpng_ver png_get_header_ver(NULL)
A
Andreas Dilger 已提交
488

489 490 491
/* This file is arranged in several sections:
 *
 * 1. Any configuration options that can be specified by for the application
492
 *    code when it is built.  (Build time configuration is in pnglibconf.h)
493 494 495
 * 2. Type definitions (base types are defined in pngconf.h), structure
 *    definitions.
 * 3. Exported library functions.
496
 * 4. Simplified API.
497 498 499 500 501
 *
 * The library source code has additional files (principally pngpriv.h) that
 * allow configuration of the library.
 */
/* Section 1: run time configuration
502
 * See pnglibconf.h for build time configuration
503 504 505
 *
 * Run time configuration allows the application to choose between
 * implementations of certain arithmetic APIs.  The default is set
506
 * at build time and recorded in pnglibconf.h, but it is safe to
507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534
 * override these (and only these) settings.  Note that this won't
 * change what the library does, only application code, and the
 * settings can (and probably should) be made on a per-file basis
 * by setting the #defines before including png.h
 *
 * Use macros to read integers from PNG data or use the exported
 * functions?
 *   PNG_USE_READ_MACROS: use the macros (see below)  Note that
 *     the macros evaluate their argument multiple times.
 *   PNG_NO_USE_READ_MACROS: call the relevant library function.
 *
 * Use the alternative algorithm for compositing alpha samples that
 * does not use division?
 *   PNG_READ_COMPOSITE_NODIV_SUPPORTED: use the 'no division'
 *      algorithm.
 *   PNG_NO_READ_COMPOSITE_NODIV: use the 'division' algorithm.
 *
 * How to handle benign errors if PNG_ALLOW_BENIGN_ERRORS is
 * false?
 *   PNG_ALLOW_BENIGN_ERRORS: map calls to the benign error
 *      APIs to png_warning.
 * Otherwise the calls are mapped to png_error.
 */

/* Section 2: type definitions, including structures and compile time
 * constants.
 * See pngconf.h for base types that vary by machine/system
 */
535 536 537 538

/* This triggers a compiler error in png.c, if png.c and png.h
 * do not agree upon the version number.
 */
539
typedef char* png_libpng_version_1_6_5beta01;
540

541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581
/* Basic control structions.  Read libpng-manual.txt or libpng.3 for more info.
 *
 * png_struct is the cache of information used while reading or writing a single
 * PNG file.  One of these is always required, although the simplified API
 * (below) hides the creation and destruction of it.
 */
typedef struct png_struct_def png_struct;
typedef const png_struct * png_const_structp;
typedef png_struct * png_structp;
typedef png_struct * * png_structpp;

/* png_info contains information read from or to be written to a PNG file.  One
 * or more of these must exist while reading or creating a PNG file.  The
 * information is not used by libpng during read but is used to control what
 * gets written when a PNG file is created.  "png_get_" function calls read
 * information during read and "png_set_" functions calls write information
 * when creating a PNG.
 * been moved into a separate header file that is not accessible to
 * applications.  Read libpng-manual.txt or libpng.3 for more info.
 */
typedef struct png_info_def png_info;
typedef png_info * png_infop;
typedef const png_info * png_const_infop;
typedef png_info * * png_infopp;

/* Types with names ending 'p' are pointer types.  The corresponding types with
 * names ending 'rp' are identical pointer types except that the pointer is
 * marked 'restrict', which means that it is the only pointer to the object
 * passed to the function.  Applications should not use the 'restrict' types;
 * it is always valid to pass 'p' to a pointer with a function argument of the
 * corresponding 'rp' type.  Different compilers have different rules with
 * regard to type matching in the presence of 'restrict'.  For backward
 * compatibility libpng callbacks never have 'restrict' in their parameters and,
 * consequentially, writing portable application code is extremely difficult if
 * an attempt is made to use 'restrict'.
 */
typedef png_struct * PNG_RESTRICT png_structrp;
typedef const png_struct * PNG_RESTRICT png_const_structrp;
typedef png_info * PNG_RESTRICT png_inforp;
typedef const png_info * PNG_RESTRICT png_const_inforp;

A
Andreas Dilger 已提交
582 583 584 585
/* Three color definitions.  The order of the red, green, and blue, (and the
 * exact size) is not important, although the size of the fields need to
 * be png_byte or png_uint_16 (as defined below).
 */
G
Guy Schalnat 已提交
586 587
typedef struct png_color_struct
{
G
Guy Schalnat 已提交
588
   png_byte red;
G
Guy Schalnat 已提交
589 590 591
   png_byte green;
   png_byte blue;
} png_color;
592 593 594
typedef png_color * png_colorp;
typedef const png_color * png_const_colorp;
typedef png_color * * png_colorpp;
G
Guy Schalnat 已提交
595 596 597

typedef struct png_color_16_struct
{
A
Andreas Dilger 已提交
598 599
   png_byte index;    /* used for palette files */
   png_uint_16 red;   /* for use in red green blue files */
G
Guy Schalnat 已提交
600 601
   png_uint_16 green;
   png_uint_16 blue;
A
Andreas Dilger 已提交
602
   png_uint_16 gray;  /* for use in grayscale files */
G
Guy Schalnat 已提交
603
} png_color_16;
604 605 606
typedef png_color_16 * png_color_16p;
typedef const png_color_16 * png_const_color_16p;
typedef png_color_16 * * png_color_16pp;
G
Guy Schalnat 已提交
607 608 609

typedef struct png_color_8_struct
{
A
Andreas Dilger 已提交
610
   png_byte red;   /* for use in red green blue files */
G
Guy Schalnat 已提交
611 612
   png_byte green;
   png_byte blue;
A
Andreas Dilger 已提交
613
   png_byte gray;  /* for use in grayscale files */
G
Guy Schalnat 已提交
614 615
   png_byte alpha; /* for alpha channel files */
} png_color_8;
616 617 618
typedef png_color_8 * png_color_8p;
typedef const png_color_8 * png_const_color_8p;
typedef png_color_8 * * png_color_8pp;
G
Guy Schalnat 已提交
619

620 621 622 623
/*
 * The following two structures are used for the in-core representation
 * of sPLT chunks.
 */
624
typedef struct png_sPLT_entry_struct
625 626 627 628 629 630
{
   png_uint_16 red;
   png_uint_16 green;
   png_uint_16 blue;
   png_uint_16 alpha;
   png_uint_16 frequency;
631
} png_sPLT_entry;
632 633 634
typedef png_sPLT_entry * png_sPLT_entryp;
typedef const png_sPLT_entry * png_const_sPLT_entryp;
typedef png_sPLT_entry * * png_sPLT_entrypp;
635

636 637 638 639 640
/*  When the depth of the sPLT palette is 8 bits, the color and alpha samples
 *  occupy the LSB of their respective members, and the MSB of each member
 *  is zero-filled.  The frequency member always occupies the full 16 bits.
 */

641
typedef struct png_sPLT_struct
642
{
643 644 645 646
   png_charp name;           /* palette name */
   png_byte depth;           /* depth of palette samples */
   png_sPLT_entryp entries;  /* palette entries */
   png_int_32 nentries;      /* number of palette entries */
647
} png_sPLT_t;
648 649 650
typedef png_sPLT_t * png_sPLT_tp;
typedef const png_sPLT_t * png_const_sPLT_tp;
typedef png_sPLT_t * * png_sPLT_tpp;
651 652

#ifdef PNG_TEXT_SUPPORTED
653
/* png_text holds the contents of a text/ztxt/itxt chunk in a PNG file,
654
 * and whether that contents is compressed or not.  The "key" field
655 656
 * points to a regular zero-terminated C string.  The "text" fields can be a
 * regular C string, an empty string, or a NULL pointer.
657
 * However, the structure returned by png_get_text() will always contain
658 659 660 661 662 663 664 665
 * the "text" field as a regular zero-terminated C string (possibly
 * empty), never a NULL pointer, so it can be safely used in printf() and
 * other string-handling functions.  Note that the "itxt_length", "lang", and
 * "lang_key" members of the structure only exist when the library is built
 * with iTXt chunk support.  Prior to libpng-1.4.0 the library was built by
 * default without iTXt support. Also note that when iTXt *is* supported,
 * the "lang" and "lang_key" fields contain NULL pointers when the
 * "compression" field contains * PNG_TEXT_COMPRESSION_NONE or
666 667 668
 * PNG_TEXT_COMPRESSION_zTXt. Note that the "compression value" is not the
 * same as what appears in the PNG tEXt/zTXt/iTXt chunk's "compression flag"
 * which is always 0 or 1, or its "compression method" which is always 0.
669
 */
G
Guy Schalnat 已提交
670 671
typedef struct png_text_struct
{
672 673 674 675 676
   int  compression;       /* compression value:
                             -1: tEXt, none
                              0: zTXt, deflate
                              1: iTXt, none
                              2: iTXt, deflate  */
A
Andreas Dilger 已提交
677
   png_charp key;          /* keyword, 1-79 character description of "text" */
678 679
   png_charp text;         /* comment, may be an empty string (ie "")
                              or a NULL pointer */
680 681
   png_size_t text_length; /* length of the text string */
   png_size_t itxt_length; /* length of the itxt string */
682 683
   png_charp lang;         /* language code, 0-79 characters
                              or a NULL pointer */
684
   png_charp lang_key;     /* keyword translated UTF-8 string, 0 or more
685
                              chars or a NULL pointer */
G
Guy Schalnat 已提交
686
} png_text;
687 688 689
typedef png_text * png_textp;
typedef const png_text * png_const_textp;
typedef png_text * * png_textpp;
690
#endif
A
Andreas Dilger 已提交
691 692 693 694 695 696 697

/* Supported compression types for text in PNG files (tEXt, and zTXt).
 * The values of the PNG_TEXT_COMPRESSION_ defines should NOT be changed. */
#define PNG_TEXT_COMPRESSION_NONE_WR -3
#define PNG_TEXT_COMPRESSION_zTXt_WR -2
#define PNG_TEXT_COMPRESSION_NONE    -1
#define PNG_TEXT_COMPRESSION_zTXt     0
698 699 700
#define PNG_ITXT_COMPRESSION_NONE     1
#define PNG_ITXT_COMPRESSION_zTXt     2
#define PNG_TEXT_COMPRESSION_LAST     3  /* Not a valid value */
G
Guy Schalnat 已提交
701 702

/* png_time is a way to hold the time in an machine independent way.
703 704 705
 * Two conversions are provided, both from time_t and struct tm.  There
 * is no portable way to convert to either of these structures, as far
 * as I know.  If you know of a portable way, send it to me.  As a side
706
 * note - PNG has always been Year 2000 compliant!
707
 */
G
Guy Schalnat 已提交
708 709 710
typedef struct png_time_struct
{
   png_uint_16 year; /* full year, as in, 1995 */
A
Andreas Dilger 已提交
711 712 713 714 715
   png_byte month;   /* month of year, 1 - 12 */
   png_byte day;     /* day of month, 1 - 31 */
   png_byte hour;    /* hour of day, 0 - 23 */
   png_byte minute;  /* minute of hour, 0 - 59 */
   png_byte second;  /* second of minute, 0 - 60 (for leap seconds) */
G
Guy Schalnat 已提交
716
} png_time;
717 718 719
typedef png_time * png_timep;
typedef const png_time * png_const_timep;
typedef png_time * * png_timepp;
A
Andreas Dilger 已提交
720

721
#ifdef PNG_STORE_UNKNOWN_CHUNKS_SUPPORTED
722 723 724 725
/* png_unknown_chunk is a structure to hold queued chunks for which there is
 * no specific support.  The idea is that we can use this to queue
 * up private chunks for output even though the library doesn't actually
 * know about their semantics.
726 727
 *
 * The data in the structure is set by libpng on read and used on write.
728 729 730
 */
typedef struct png_unknown_chunk_t
{
731 732
    png_byte name[5]; /* Textual chunk name with '\0' terminator */
    png_byte *data;   /* Data, should not be modified on read! */
733 734
    png_size_t size;

735 736 737 738 739 740
    /* On write 'location' must be set using the flag values listed below.
     * Notice that on read it is set by libpng however the values stored have
     * more bits set than are listed below.  Always treat the value as a
     * bitmask.  On write set only one bit - setting multiple bits may cause the
     * chunk to be written in multiple places.
     */
741 742 743
    png_byte location; /* mode of operation at read time */
}
png_unknown_chunk;
744

745 746 747
typedef png_unknown_chunk * png_unknown_chunkp;
typedef const png_unknown_chunk * png_const_unknown_chunkp;
typedef png_unknown_chunk * * png_unknown_chunkpp;
748 749
#endif

750
/* Flag values for the unknown chunk location byte. */
751 752 753
#define PNG_HAVE_IHDR  0x01
#define PNG_HAVE_PLTE  0x02
#define PNG_AFTER_IDAT 0x08
754

755
/* Maximum positive integer used in PNG is (2^31)-1 */
756
#define PNG_UINT_31_MAX ((png_uint_32)0x7fffffffL)
757 758
#define PNG_UINT_32_MAX ((png_uint_32)(-1))
#define PNG_SIZE_MAX ((png_size_t)(-1))
759

G
[devel]  
Glenn Randers-Pehrson 已提交
760 761 762 763 764
/* These are constants for fixed point values encoded in the
 * PNG specification manner (x100000)
 */
#define PNG_FP_1    100000
#define PNG_FP_HALF  50000
765 766
#define PNG_FP_MAX  ((png_fixed_point)0x7fffffffL)
#define PNG_FP_MIN  (-PNG_FP_MAX)
G
[devel]  
Glenn Randers-Pehrson 已提交
767

A
Andreas Dilger 已提交
768
/* These describe the color_type field in png_info. */
G
Guy Schalnat 已提交
769
/* color type masks */
A
Andreas Dilger 已提交
770 771 772
#define PNG_COLOR_MASK_PALETTE    1
#define PNG_COLOR_MASK_COLOR      2
#define PNG_COLOR_MASK_ALPHA      4
G
Guy Schalnat 已提交
773 774

/* color types.  Note that not all combinations are legal */
G
Guy Schalnat 已提交
775
#define PNG_COLOR_TYPE_GRAY 0
A
Andreas Dilger 已提交
776 777 778
#define PNG_COLOR_TYPE_PALETTE  (PNG_COLOR_MASK_COLOR | PNG_COLOR_MASK_PALETTE)
#define PNG_COLOR_TYPE_RGB        (PNG_COLOR_MASK_COLOR)
#define PNG_COLOR_TYPE_RGB_ALPHA  (PNG_COLOR_MASK_COLOR | PNG_COLOR_MASK_ALPHA)
G
Guy Schalnat 已提交
779
#define PNG_COLOR_TYPE_GRAY_ALPHA (PNG_COLOR_MASK_ALPHA)
780 781 782
/* aliases */
#define PNG_COLOR_TYPE_RGBA  PNG_COLOR_TYPE_RGB_ALPHA
#define PNG_COLOR_TYPE_GA  PNG_COLOR_TYPE_GRAY_ALPHA
G
Guy Schalnat 已提交
783

784
/* This is for compression type. PNG 1.0-1.2 only define the single type. */
A
Andreas Dilger 已提交
785 786 787
#define PNG_COMPRESSION_TYPE_BASE 0 /* Deflate method 8, 32K window */
#define PNG_COMPRESSION_TYPE_DEFAULT PNG_COMPRESSION_TYPE_BASE

788
/* This is for filter type. PNG 1.0-1.2 only define the single type. */
A
Andreas Dilger 已提交
789
#define PNG_FILTER_TYPE_BASE      0 /* Single row per-byte filtering */
790
#define PNG_INTRAPIXEL_DIFFERENCING 64 /* Used only in MNG datastreams */
A
Andreas Dilger 已提交
791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809
#define PNG_FILTER_TYPE_DEFAULT   PNG_FILTER_TYPE_BASE

/* These are for the interlacing type.  These values should NOT be changed. */
#define PNG_INTERLACE_NONE        0 /* Non-interlaced image */
#define PNG_INTERLACE_ADAM7       1 /* Adam7 interlacing */
#define PNG_INTERLACE_LAST        2 /* Not a valid value */

/* These are for the oFFs chunk.  These values should NOT be changed. */
#define PNG_OFFSET_PIXEL          0 /* Offset in pixels */
#define PNG_OFFSET_MICROMETER     1 /* Offset in micrometers (1/10^6 meter) */
#define PNG_OFFSET_LAST           2 /* Not a valid value */

/* These are for the pCAL chunk.  These values should NOT be changed. */
#define PNG_EQUATION_LINEAR       0 /* Linear transformation */
#define PNG_EQUATION_BASE_E       1 /* Exponential base e transform */
#define PNG_EQUATION_ARBITRARY    2 /* Arbitrary base exponential transform */
#define PNG_EQUATION_HYPERBOLIC   3 /* Hyperbolic sine transformation */
#define PNG_EQUATION_LAST         4 /* Not a valid value */

810 811 812 813 814 815
/* These are for the sCAL chunk.  These values should NOT be changed. */
#define PNG_SCALE_UNKNOWN         0 /* unknown unit (image scale) */
#define PNG_SCALE_METER           1 /* meters per pixel */
#define PNG_SCALE_RADIAN          2 /* radians per pixel */
#define PNG_SCALE_LAST            3 /* Not a valid value */

A
Andreas Dilger 已提交
816 817 818 819 820
/* These are for the pHYs chunk.  These values should NOT be changed. */
#define PNG_RESOLUTION_UNKNOWN    0 /* pixels/unknown unit (aspect ratio) */
#define PNG_RESOLUTION_METER      1 /* pixels/meter */
#define PNG_RESOLUTION_LAST       2 /* Not a valid value */

821
/* These are for the sRGB chunk.  These values should NOT be changed. */
822 823 824 825
#define PNG_sRGB_INTENT_PERCEPTUAL 0
#define PNG_sRGB_INTENT_RELATIVE   1
#define PNG_sRGB_INTENT_SATURATION 2
#define PNG_sRGB_INTENT_ABSOLUTE   3
826
#define PNG_sRGB_INTENT_LAST       4 /* Not a valid value */
827

828 829
/* This is for text chunks */
#define PNG_KEYWORD_MAX_LENGTH     79
830

831
/* Maximum number of entries in PLTE/sPLT/tRNS arrays */
832
#define PNG_MAX_PALETTE_LENGTH    256
833

A
Andreas Dilger 已提交
834 835 836 837 838
/* These determine if an ancillary chunk's data has been successfully read
 * from the PNG header, or if the application has filled in the corresponding
 * data in the info_struct to be written into the output file.  The values
 * of the PNG_INFO_<chunk> defines should NOT be changed.
 */
G
Guy Schalnat 已提交
839 840 841 842 843 844 845 846 847 848
#define PNG_INFO_gAMA 0x0001
#define PNG_INFO_sBIT 0x0002
#define PNG_INFO_cHRM 0x0004
#define PNG_INFO_PLTE 0x0008
#define PNG_INFO_tRNS 0x0010
#define PNG_INFO_bKGD 0x0020
#define PNG_INFO_hIST 0x0040
#define PNG_INFO_pHYs 0x0080
#define PNG_INFO_oFFs 0x0100
#define PNG_INFO_tIME 0x0200
A
Andreas Dilger 已提交
849
#define PNG_INFO_pCAL 0x0400
850
#define PNG_INFO_sRGB 0x0800   /* GR-P, 0.96a */
851 852 853
#define PNG_INFO_iCCP 0x1000   /* ESR, 1.0.6 */
#define PNG_INFO_sPLT 0x2000   /* ESR, 1.0.6 */
#define PNG_INFO_sCAL 0x4000   /* ESR, 1.0.6 */
854
#define PNG_INFO_IDAT 0x8000   /* ESR, 1.0.6 */
G
Guy Schalnat 已提交
855

A
Andreas Dilger 已提交
856 857 858 859
/* This is used for the transformation routines, as some of them
 * change these values for the row.  It also should enable using
 * the routines for other purposes.
 */
G
Guy Schalnat 已提交
860 861
typedef struct png_row_info_struct
{
862 863 864 865 866
   png_uint_32 width;    /* width of row */
   png_size_t rowbytes;  /* number of bytes in row */
   png_byte color_type;  /* color type of row */
   png_byte bit_depth;   /* bit depth of row */
   png_byte channels;    /* number of channels (1, 2, 3, or 4) */
G
Guy Schalnat 已提交
867
   png_byte pixel_depth; /* bits per pixel (depth * channels) */
G
Guy Schalnat 已提交
868 869
} png_row_info;

870 871
typedef png_row_info * png_row_infop;
typedef png_row_info * * png_row_infopp;
G
Guy Schalnat 已提交
872

873 874 875 876
/* These are the function types for the I/O functions and for the functions
 * that allow the user to override the default I/O functions with his or her
 * own.  The png_error_ptr type should match that of user-supplied warning
 * and error functions, while the png_rw_ptr type should match that of the
877
 * user read/write data functions.  Note that the 'write' function must not
878
 * modify the buffer it is passed. The 'read' function, on the other hand, is
879
 * expected to return the read data in the buffer.
G
Guy Schalnat 已提交
880
 */
881 882 883 884 885 886 887
typedef PNG_CALLBACK(void, *png_error_ptr, (png_structp, png_const_charp));
typedef PNG_CALLBACK(void, *png_rw_ptr, (png_structp, png_bytep, png_size_t));
typedef PNG_CALLBACK(void, *png_flush_ptr, (png_structp));
typedef PNG_CALLBACK(void, *png_read_status_ptr, (png_structp, png_uint_32,
    int));
typedef PNG_CALLBACK(void, *png_write_status_ptr, (png_structp, png_uint_32,
    int));
888

G
Guy Schalnat 已提交
889
#ifdef PNG_PROGRESSIVE_READ_SUPPORTED
890 891
typedef PNG_CALLBACK(void, *png_progressive_info_ptr, (png_structp, png_infop));
typedef PNG_CALLBACK(void, *png_progressive_end_ptr, (png_structp, png_infop));
892 893 894 895 896 897 898 899 900 901 902

/* The following callback receives png_uint_32 row_number, int pass for the
 * png_bytep data of the row.  When transforming an interlaced image the
 * row number is the row number within the sub-image of the interlace pass, so
 * the value will increase to the height of the sub-image (not the full image)
 * then reset to 0 for the next pass.
 *
 * Use PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
 * find the output pixel (x,y) given an interlaced sub-image pixel
 * (row,col,pass).  (See below for these macros.)
 */
903
typedef PNG_CALLBACK(void, *png_progressive_row_ptr, (png_structp, png_bytep,
904
    png_uint_32, int));
905
#endif
G
Guy Schalnat 已提交
906

907
#if defined(PNG_READ_USER_TRANSFORM_SUPPORTED) || \
908
    defined(PNG_WRITE_USER_TRANSFORM_SUPPORTED)
909
typedef PNG_CALLBACK(void, *png_user_transform_ptr, (png_structp, png_row_infop,
910
    png_bytep));
911
#endif
912

913
#ifdef PNG_USER_CHUNKS_SUPPORTED
914
typedef PNG_CALLBACK(int, *png_user_chunk_ptr, (png_structp,
915
    png_unknown_chunkp));
916
#endif
917
#ifdef PNG_UNKNOWN_CHUNKS_SUPPORTED
918 919
/* not used anywhere */
/* typedef PNG_CALLBACK(void, *png_unknown_chunk_ptr, (png_structp)); */
920
#endif
921

922
#ifdef PNG_SETJMP_SUPPORTED
923 924 925 926 927 928 929
/* This must match the function definition in <setjmp.h>, and the application
 * must include this before png.h to obtain the definition of jmp_buf.  The
 * function is required to be PNG_NORETURN, but this is not checked.  If the
 * function does return the application will crash via an abort() or similar
 * system level call.
 *
 * If you get a warning here while building the library you may need to make
G
[devel]  
Glenn Randers-Pehrson 已提交
930 931 932
 * changes to ensure that pnglibconf.h records the calling convention used by
 * your compiler.  This may be very difficult - try using a different compiler
 * to build the library!
933
 */
934
PNG_FUNCTION(void, (PNGCAPI *png_longjmp_ptr), PNGARG((jmp_buf, int)), typedef);
935
#endif
936 937

/* Transform masks for the high-level interface */
938 939
#define PNG_TRANSFORM_IDENTITY       0x0000    /* read and write */
#define PNG_TRANSFORM_STRIP_16       0x0001    /* read only */
940 941
#define PNG_TRANSFORM_STRIP_ALPHA    0x0002    /* read only */
#define PNG_TRANSFORM_PACKING        0x0004    /* read and write */
942 943
#define PNG_TRANSFORM_PACKSWAP       0x0008    /* read and write */
#define PNG_TRANSFORM_EXPAND         0x0010    /* read only */
944
#define PNG_TRANSFORM_INVERT_MONO    0x0020    /* read and write */
945 946 947
#define PNG_TRANSFORM_SHIFT          0x0040    /* read and write */
#define PNG_TRANSFORM_BGR            0x0080    /* read and write */
#define PNG_TRANSFORM_SWAP_ALPHA     0x0100    /* read and write */
948
#define PNG_TRANSFORM_SWAP_ENDIAN    0x0200    /* read and write */
949
#define PNG_TRANSFORM_INVERT_ALPHA   0x0400    /* read and write */
950
#define PNG_TRANSFORM_STRIP_FILLER   0x0800    /* write only */
951
/* Added to libpng-1.2.34 */
952
#define PNG_TRANSFORM_STRIP_FILLER_BEFORE PNG_TRANSFORM_STRIP_FILLER
953 954 955
#define PNG_TRANSFORM_STRIP_FILLER_AFTER 0x1000 /* write only */
/* Added to libpng-1.4.0 */
#define PNG_TRANSFORM_GRAY_TO_RGB   0x2000      /* read only */
956
/* Added to libpng-1.5.4 */
957
#define PNG_TRANSFORM_EXPAND_16     0x4000      /* read only */
958
#define PNG_TRANSFORM_SCALE_16      0x8000      /* read only */
959

960
/* Flags for MNG supported features */
961 962
#define PNG_FLAG_MNG_EMPTY_PLTE     0x01
#define PNG_FLAG_MNG_FILTER_64      0x04
963
#define PNG_ALL_MNG_FEATURES        0x05
964

965
/* NOTE: prior to 1.5 these functions had no 'API' style declaration,
966 967 968 969 970
 * this allowed the zlib default functions to be used on Windows
 * platforms.  In 1.5 the zlib default malloc (which just calls malloc and
 * ignores the first argument) should be completely compatible with the
 * following.
 */
971
typedef PNG_CALLBACK(png_voidp, *png_malloc_ptr, (png_structp,
972 973
    png_alloc_size_t));
typedef PNG_CALLBACK(void, *png_free_ptr, (png_structp, png_voidp));
974

975 976
/* Section 3: exported functions
 * Here are the function definitions most commonly used.  This is not
977
 * the place to find out how to use libpng.  See libpng-manual.txt for the
A
Andreas Dilger 已提交
978
 * full explanation, see example.c for the summary.  This just provides
979
 * a simple one line description of the use of each function.
G
[devel]  
Glenn Randers-Pehrson 已提交
980
 *
981 982
 * The PNG_EXPORT() and PNG_EXPORTA() macros used below are defined in
 * pngconf.h and in the *.dfn files in the scripts directory.
G
[devel]  
Glenn Randers-Pehrson 已提交
983
 *
984
 *   PNG_EXPORT(ordinal, type, name, (args));
985 986 987 988 989
 *
 *       ordinal:    ordinal that is used while building
 *                   *.def files. The ordinal value is only
 *                   relevant when preprocessing png.h with
 *                   the *.dfn files for building symbol table
990
 *                   entries, and are removed by pngconf.h.
991 992 993 994
 *       type:       return type of the function
 *       name:       function name
 *       args:       function arguments, with types
 *
995 996 997
 * When we wish to append attributes to a function prototype we use
 * the PNG_EXPORTA() macro instead.
 *
998 999
 *   PNG_EXPORTA(ordinal, type, name, (args), attributes);
 *
1000
 *       ordinal, type, name, and args: same as in PNG_EXPORT().
1001
 *       attributes: function attributes
A
Andreas Dilger 已提交
1002
 */
G
Guy Schalnat 已提交
1003

1004
/* Returns the version number of the library */
1005
PNG_EXPORT(1, png_uint_32, png_access_version_number, (void));
1006

A
Andreas Dilger 已提交
1007
/* Tell lib we have already handled the first <num_bytes> magic bytes.
A
Andreas Dilger 已提交
1008 1009
 * Handling more than 8 bytes from the beginning of the file is an error.
 */
1010
PNG_EXPORT(2, void, png_set_sig_bytes, (png_structrp png_ptr, int num_bytes));
A
Andreas Dilger 已提交
1011 1012 1013 1014 1015 1016

/* Check sig[start] through sig[start + num_to_check - 1] to see if it's a
 * PNG file.  Returns zero if the supplied bytes match the 8-byte PNG
 * signature, and non-zero otherwise.  Having num_to_check == 0 or
 * start > 7 will always fail (ie return non-zero).
 */
1017
PNG_EXPORT(3, int, png_sig_cmp, (png_const_bytep sig, png_size_t start,
1018
    png_size_t num_to_check));
A
Andreas Dilger 已提交
1019

1020 1021 1022
/* Simple signature checking function.  This is the same as calling
 * png_check_sig(sig, n) := !png_sig_cmp(sig, 0, n).
 */
1023
#define png_check_sig(sig, n) !png_sig_cmp((sig), 0, (n))
1024

A
Andreas Dilger 已提交
1025
/* Allocate and initialize png_ptr struct for reading, and any other memory. */
1026 1027
PNG_EXPORTA(4, png_structp, png_create_read_struct,
    (png_const_charp user_png_ver, png_voidp error_ptr,
1028
    png_error_ptr error_fn, png_error_ptr warn_fn),
1029
    PNG_ALLOCATED);
A
Andreas Dilger 已提交
1030

1031
/* Allocate and initialize png_ptr struct for writing, and any other memory */
1032 1033
PNG_EXPORTA(5, png_structp, png_create_write_struct,
    (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn,
1034
    png_error_ptr warn_fn),
1035
    PNG_ALLOCATED);
G
Guy Schalnat 已提交
1036

1037
PNG_EXPORT(6, png_size_t, png_get_compression_buffer_size,
1038
    (png_const_structrp png_ptr));
1039

1040
PNG_EXPORT(7, void, png_set_compression_buffer_size, (png_structrp png_ptr,
1041
    png_size_t size));
1042

1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053
/* Moved from pngconf.h in 1.4.0 and modified to ensure setjmp/longjmp
 * match up.
 */
#ifdef PNG_SETJMP_SUPPORTED
/* This function returns the jmp_buf built in to *png_ptr.  It must be
 * supplied with an appropriate 'longjmp' function to use on that jmp_buf
 * unless the default error function is overridden in which case NULL is
 * acceptable.  The size of the jmp_buf is checked against the actual size
 * allocated by the library - the call will return NULL on a mismatch
 * indicating an ABI mismatch.
 */
1054
PNG_EXPORT(8, jmp_buf*, png_set_longjmp_fn, (png_structrp png_ptr,
1055
    png_longjmp_ptr longjmp_fn, size_t jmp_buf_size));
1056
#  define png_jmpbuf(png_ptr) \
1057
      (*png_set_longjmp_fn((png_ptr), longjmp, (sizeof (jmp_buf))))
1058 1059
#else
#  define png_jmpbuf(png_ptr) \
1060
      (LIBPNG_WAS_COMPILED_WITH__PNG_NO_SETJMP)
1061
#endif
1062 1063 1064 1065 1066
/* This function should be used by libpng applications in place of
 * longjmp(png_ptr->jmpbuf, val).  If longjmp_fn() has been set, it
 * will use it; otherwise it will call PNG_ABORT().  This function was
 * added in libpng-1.5.0.
 */
1067
PNG_EXPORTA(9, void, png_longjmp, (png_const_structrp png_ptr, int val),
1068
    PNG_NORETURN);
1069

1070
#ifdef PNG_READ_SUPPORTED
1071
/* Reset the compression stream */
1072
PNG_EXPORTA(10, int, png_reset_zstream, (png_structrp png_ptr), PNG_DEPRECATED);
1073
#endif
1074

1075
/* New functions added in libpng-1.0.2 (not enabled by default until 1.2.0) */
1076
#ifdef PNG_USER_MEM_SUPPORTED
1077 1078
PNG_EXPORTA(11, png_structp, png_create_read_struct_2,
    (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn,
1079 1080
    png_error_ptr warn_fn,
    png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn),
1081 1082 1083
    PNG_ALLOCATED);
PNG_EXPORTA(12, png_structp, png_create_write_struct_2,
    (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn,
1084 1085
    png_error_ptr warn_fn,
    png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn),
1086
    PNG_ALLOCATED);
1087 1088
#endif

1089
/* Write the PNG file signature. */
1090
PNG_EXPORT(13, void, png_write_sig, (png_structrp png_ptr));
1091

1092
/* Write a PNG chunk - size, type, (optional) data, CRC. */
1093
PNG_EXPORT(14, void, png_write_chunk, (png_structrp png_ptr, png_const_bytep
1094
    chunk_name, png_const_bytep data, png_size_t length));
1095 1096

/* Write the start of a PNG chunk - length and chunk name. */
1097
PNG_EXPORT(15, void, png_write_chunk_start, (png_structrp png_ptr,
1098
    png_const_bytep chunk_name, png_uint_32 length));
1099 1100

/* Write the data of a PNG chunk started with png_write_chunk_start(). */
1101
PNG_EXPORT(16, void, png_write_chunk_data, (png_structrp png_ptr,
1102
    png_const_bytep data, png_size_t length));
1103 1104

/* Finish a chunk started with png_write_chunk_start() (includes CRC). */
1105
PNG_EXPORT(17, void, png_write_chunk_end, (png_structrp png_ptr));
1106

A
Andreas Dilger 已提交
1107
/* Allocate and initialize the info structure */
1108
PNG_EXPORTA(18, png_infop, png_create_info_struct, (png_const_structrp png_ptr),
1109
    PNG_ALLOCATED);
G
Guy Schalnat 已提交
1110

1111 1112 1113 1114
/* DEPRECATED: this function allowed init structures to be created using the
 * default allocation method (typically malloc).  Use is deprecated in 1.6.0 and
 * the API will be removed in the future.
 */
1115 1116
PNG_EXPORTA(19, void, png_info_init_3, (png_infopp info_ptr,
    png_size_t png_info_struct_size), PNG_DEPRECATED);
G
Guy Schalnat 已提交
1117

A
Andreas Dilger 已提交
1118
/* Writes all the PNG information before the image. */
1119
PNG_EXPORT(20, void, png_write_info_before_PLTE,
1120
    (png_structrp png_ptr, png_const_inforp info_ptr));
1121
PNG_EXPORT(21, void, png_write_info,
1122
    (png_structrp png_ptr, png_const_inforp info_ptr));
G
Guy Schalnat 已提交
1123

1124
#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
1125
/* Read the information before the actual image data. */
1126
PNG_EXPORT(22, void, png_read_info,
1127
    (png_structrp png_ptr, png_inforp info_ptr));
1128
#endif
G
Guy Schalnat 已提交
1129

1130
#ifdef PNG_TIME_RFC1123_SUPPORTED
1131 1132 1133 1134 1135
   /* Convert to a US string format: there is no localization support in this
    * routine.  The original implementation used a 29 character buffer in
    * png_struct, this will be removed in future versions.
    */
#if PNG_LIBPNG_VER < 10700
1136
/* To do: remove this from libpng17 (and from libpng17/png.c and pngstruct.h) */
1137
PNG_EXPORTA(23, png_const_charp, png_convert_to_rfc1123, (png_structrp png_ptr,
1138 1139 1140
    png_const_timep ptime),PNG_DEPRECATED);
#endif
PNG_EXPORT(241, int, png_convert_to_rfc1123_buffer, (char out[29],
1141
    png_const_timep ptime));
1142
#endif
1143

1144
#ifdef PNG_CONVERT_tIME_SUPPORTED
1145
/* Convert from a struct tm to png_time */
1146
PNG_EXPORT(24, void, png_convert_from_struct_tm, (png_timep ptime,
1147
    const struct tm * ttime));
G
Guy Schalnat 已提交
1148

1149
/* Convert from time_t to png_time.  Uses gmtime() */
1150
PNG_EXPORT(25, void, png_convert_from_time_t, (png_timep ptime, time_t ttime));
1151
#endif /* PNG_CONVERT_tIME_SUPPORTED */
G
Guy Schalnat 已提交
1152

1153
#ifdef PNG_READ_EXPAND_SUPPORTED
1154
/* Expand data to 24-bit RGB, or 8-bit grayscale, with alpha if available. */
1155 1156 1157 1158
PNG_EXPORT(26, void, png_set_expand, (png_structrp png_ptr));
PNG_EXPORT(27, void, png_set_expand_gray_1_2_4_to_8, (png_structrp png_ptr));
PNG_EXPORT(28, void, png_set_palette_to_rgb, (png_structrp png_ptr));
PNG_EXPORT(29, void, png_set_tRNS_to_alpha, (png_structrp png_ptr));
1159
#endif
G
Guy Schalnat 已提交
1160

1161
#ifdef PNG_READ_EXPAND_16_SUPPORTED
1162
/* Expand to 16-bit channels, forces conversion of palette to RGB and expansion
1163 1164
 * of a tRNS chunk if present.
 */
1165
PNG_EXPORT(221, void, png_set_expand_16, (png_structrp png_ptr));
1166 1167
#endif

G
Guy Schalnat 已提交
1168
#if defined(PNG_READ_BGR_SUPPORTED) || defined(PNG_WRITE_BGR_SUPPORTED)
G
Guy Schalnat 已提交
1169
/* Use blue, green, red order for pixels. */
1170
PNG_EXPORT(30, void, png_set_bgr, (png_structrp png_ptr));
1171
#endif
G
Guy Schalnat 已提交
1172

1173
#ifdef PNG_READ_GRAY_TO_RGB_SUPPORTED
1174
/* Expand the grayscale to 24-bit RGB if necessary. */
1175
PNG_EXPORT(31, void, png_set_gray_to_rgb, (png_structrp png_ptr));
1176
#endif
G
Guy Schalnat 已提交
1177

1178
#ifdef PNG_READ_RGB_TO_GRAY_SUPPORTED
1179
/* Reduce RGB to grayscale. */
1180 1181 1182 1183 1184
#define PNG_ERROR_ACTION_NONE  1
#define PNG_ERROR_ACTION_WARN  2
#define PNG_ERROR_ACTION_ERROR 3
#define PNG_RGB_TO_GRAY_DEFAULT (-1)/*for red/green coefficients*/

1185
PNG_FP_EXPORT(32, void, png_set_rgb_to_gray, (png_structrp png_ptr,
1186
    int error_action, double red, double green))
1187
PNG_FIXED_EXPORT(33, void, png_set_rgb_to_gray_fixed, (png_structrp png_ptr,
1188
    int error_action, png_fixed_point red, png_fixed_point green))
1189

1190
PNG_EXPORT(34, png_byte, png_get_rgb_to_gray_status, (png_const_structrp
1191
    png_ptr));
1192
#endif
A
Andreas Dilger 已提交
1193

1194
#ifdef PNG_BUILD_GRAYSCALE_PALETTE_SUPPORTED
1195
PNG_EXPORT(35, void, png_build_grayscale_palette, (int bit_depth,
1196
    png_colorp palette));
1197
#endif
A
Andreas Dilger 已提交
1198

1199 1200
#ifdef PNG_READ_ALPHA_MODE_SUPPORTED
/* How the alpha channel is interpreted - this affects how the color channels of
1201 1202
 * a PNG file are returned when an alpha channel, or tRNS chunk in a palette
 * file, is present.
1203
 *
1204 1205 1206 1207 1208
 * This has no effect on the way pixels are written into a PNG output
 * datastream. The color samples in a PNG datastream are never premultiplied
 * with the alpha samples.
 *
 * The default is to return data according to the PNG specification: the alpha
1209
 * channel is a linear measure of the contribution of the pixel to the
1210 1211 1212 1213
 * corresponding composited pixel.  The gamma encoded color channels must be
 * scaled according to the contribution and to do this it is necessary to undo
 * the encoding, scale the color values, perform the composition and reencode
 * the values.  This is the 'PNG' mode.
1214 1215 1216 1217 1218
 *
 * The alternative is to 'associate' the alpha with the color information by
 * storing color channel values that have been scaled by the alpha.  The
 * advantage is that the color channels can be resampled (the image can be
 * scaled) in this form.  The disadvantage is that normal practice is to store
1219 1220
 * linear, not (gamma) encoded, values and this requires 16-bit channels for
 * still images rather than the 8-bit channels that are just about sufficient if
1221 1222
 * gamma encoding is used.  In addition all non-transparent pixel values,
 * including completely opaque ones, must be gamma encoded to produce the final
1223
 * image.  This is the 'STANDARD', 'ASSOCIATED' or 'PREMULTIPLIED' mode (the
1224 1225 1226 1227 1228 1229 1230 1231
 * latter being the two common names for associated alpha color channels.)
 *
 * Since it is not necessary to perform arithmetic on opaque color values so
 * long as they are not to be resampled and are in the final color space it is
 * possible to optimize the handling of alpha by storing the opaque pixels in
 * the PNG format (adjusted for the output color space) while storing partially
 * opaque pixels in the standard, linear, format.  The accuracy required for
 * standard alpha composition is relatively low, because the pixels are
1232
 * isolated, therefore typically the accuracy loss in storing 8-bit linear
1233
 * values is acceptable.  (This is not true if the alpha channel is used to
1234 1235
 * simulate transparency over large areas - use 16 bits or the PNG mode in
 * this case!)  This is the 'OPTIMIZED' mode.  For this mode a pixel is
1236 1237 1238 1239 1240 1241 1242 1243 1244 1245
 * treated as opaque only if the alpha value is equal to the maximum value.
 *
 * The final choice is to gamma encode the alpha channel as well.  This is
 * broken because, in practice, no implementation that uses this choice
 * correctly undoes the encoding before handling alpha composition.  Use this
 * choice only if other serious errors in the software or hardware you use
 * mandate it; the typical serious error is for dark halos to appear around
 * opaque areas of the composited PNG image because of arithmetic overflow.
 *
 * The API function png_set_alpha_mode specifies which of these choices to use
1246
 * with an enumerated 'mode' value and the gamma of the required output:
1247 1248 1249 1250 1251 1252 1253 1254
 */
#define PNG_ALPHA_PNG           0 /* according to the PNG standard */
#define PNG_ALPHA_STANDARD      1 /* according to Porter/Duff */
#define PNG_ALPHA_ASSOCIATED    1 /* as above; this is the normal practice */
#define PNG_ALPHA_PREMULTIPLIED 1 /* as above */
#define PNG_ALPHA_OPTIMIZED     2 /* 'PNG' for opaque pixels, else 'STANDARD' */
#define PNG_ALPHA_BROKEN        3 /* the alpha channel is gamma encoded */

1255
PNG_FP_EXPORT(227, void, png_set_alpha_mode, (png_structrp png_ptr, int mode,
1256
    double output_gamma))
1257
PNG_FIXED_EXPORT(228, void, png_set_alpha_mode_fixed, (png_structrp png_ptr,
1258
    int mode, png_fixed_point output_gamma))
1259
#endif
1260

1261
#if defined(PNG_GAMMA_SUPPORTED) || defined(PNG_READ_ALPHA_MODE_SUPPORTED)
1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314
/* The output_gamma value is a screen gamma in libpng terminology: it expresses
 * how to decode the output values, not how they are encoded.  The values used
 * correspond to the normal numbers used to describe the overall gamma of a
 * computer display system; for example 2.2 for an sRGB conformant system.  The
 * values are scaled by 100000 in the _fixed version of the API (so 220000 for
 * sRGB.)
 *
 * The inverse of the value is always used to provide a default for the PNG file
 * encoding if it has no gAMA chunk and if png_set_gamma() has not been called
 * to override the PNG gamma information.
 *
 * When the ALPHA_OPTIMIZED mode is selected the output gamma is used to encode
 * opaque pixels however pixels with lower alpha values are not encoded,
 * regardless of the output gamma setting.
 *
 * When the standard Porter Duff handling is requested with mode 1 the output
 * encoding is set to be linear and the output_gamma value is only relevant
 * as a default for input data that has no gamma information.  The linear output
 * encoding will be overridden if png_set_gamma() is called - the results may be
 * highly unexpected!
 *
 * The following numbers are derived from the sRGB standard and the research
 * behind it.  sRGB is defined to be approximated by a PNG gAMA chunk value of
 * 0.45455 (1/2.2) for PNG.  The value implicitly includes any viewing
 * correction required to take account of any differences in the color
 * environment of the original scene and the intended display environment; the
 * value expresses how to *decode* the image for display, not how the original
 * data was *encoded*.
 *
 * sRGB provides a peg for the PNG standard by defining a viewing environment.
 * sRGB itself, and earlier TV standards, actually use a more complex transform
 * (a linear portion then a gamma 2.4 power law) than PNG can express.  (PNG is
 * limited to simple power laws.)  By saying that an image for direct display on
 * an sRGB conformant system should be stored with a gAMA chunk value of 45455
 * (11.3.3.2 and 11.3.3.5 of the ISO PNG specification) the PNG specification
 * makes it possible to derive values for other display systems and
 * environments.
 *
 * The Mac value is deduced from the sRGB based on an assumption that the actual
 * extra viewing correction used in early Mac display systems was implemented as
 * a power 1.45 lookup table.
 *
 * Any system where a programmable lookup table is used or where the behavior of
 * the final display device characteristics can be changed requires system
 * specific code to obtain the current characteristic.  However this can be
 * difficult and most PNG gamma correction only requires an approximate value.
 *
 * By default, if png_set_alpha_mode() is not called, libpng assumes that all
 * values are unencoded, linear, values and that the output device also has a
 * linear characteristic.  This is only very rarely correct - it is invariably
 * better to call png_set_alpha_mode() with PNG_DEFAULT_sRGB than rely on the
 * default if you don't know what the right answer is!
 *
1315 1316 1317 1318 1319 1320 1321
 * The special value PNG_GAMMA_MAC_18 indicates an older Mac system (pre Mac OS
 * 10.6) which used a correction table to implement a somewhat lower gamma on an
 * otherwise sRGB system.
 *
 * Both these values are reserved (not simple gamma values) in order to allow
 * more precise correction internally in the future.
 *
1322 1323 1324 1325
 * NOTE: the following values can be passed to either the fixed or floating
 * point APIs, but the floating point API will also accept floating point
 * values.
 */
1326 1327
#define PNG_DEFAULT_sRGB -1       /* sRGB gamma and color space */
#define PNG_GAMMA_MAC_18 -2       /* Old Mac '1.8' gamma and color space */
1328
#define PNG_GAMMA_sRGB   220000   /* Television standards--matches sRGB gamma */
1329
#define PNG_GAMMA_LINEAR PNG_FP_1 /* Linear */
1330
#endif
1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346

/* The following are examples of calls to png_set_alpha_mode to achieve the
 * required overall gamma correction and, where necessary, alpha
 * premultiplication.
 *
 * png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB);
 *    This is the default libpng handling of the alpha channel - it is not
 *    pre-multiplied into the color components.  In addition the call states
 *    that the output is for a sRGB system and causes all PNG files without gAMA
 *    chunks to be assumed to be encoded using sRGB.
 *
 * png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC);
 *    In this case the output is assumed to be something like an sRGB conformant
 *    display preceeded by a power-law lookup table of power 1.45.  This is how
 *    early Mac systems behaved.
 *
1347
 * png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_GAMMA_LINEAR);
1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369
 *    This is the classic Jim Blinn approach and will work in academic
 *    environments where everything is done by the book.  It has the shortcoming
 *    of assuming that input PNG data with no gamma information is linear - this
 *    is unlikely to be correct unless the PNG files where generated locally.
 *    Most of the time the output precision will be so low as to show
 *    significant banding in dark areas of the image.
 *
 * png_set_expand_16(pp);
 * png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_DEFAULT_sRGB);
 *    This is a somewhat more realistic Jim Blinn inspired approach.  PNG files
 *    are assumed to have the sRGB encoding if not marked with a gamma value and
 *    the output is always 16 bits per component.  This permits accurate scaling
 *    and processing of the data.  If you know that your input PNG files were
 *    generated locally you might need to replace PNG_DEFAULT_sRGB with the
 *    correct value for your system.
 *
 * png_set_alpha_mode(pp, PNG_ALPHA_OPTIMIZED, PNG_DEFAULT_sRGB);
 *    If you just need to composite the PNG image onto an existing background
 *    and if you control the code that does this you can use the optimization
 *    setting.  In this case you just copy completely opaque pixels to the
 *    output.  For pixels that are not completely transparent (you just skip
 *    those) you do the composition math using png_composite or png_composite_16
1370
 *    below then encode the resultant 8-bit or 16-bit values to match the output
1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407
 *    encoding.
 *
 * Other cases
 *    If neither the PNG nor the standard linear encoding work for you because
 *    of the software or hardware you use then you have a big problem.  The PNG
 *    case will probably result in halos around the image.  The linear encoding
 *    will probably result in a washed out, too bright, image (it's actually too
 *    contrasty.)  Try the ALPHA_OPTIMIZED mode above - this will probably
 *    substantially reduce the halos.  Alternatively try:
 *
 * png_set_alpha_mode(pp, PNG_ALPHA_BROKEN, PNG_DEFAULT_sRGB);
 *    This option will also reduce the halos, but there will be slight dark
 *    halos round the opaque parts of the image where the background is light.
 *    In the OPTIMIZED mode the halos will be light halos where the background
 *    is dark.  Take your pick - the halos are unavoidable unless you can get
 *    your hardware/software fixed!  (The OPTIMIZED approach is slightly
 *    faster.)
 *
 * When the default gamma of PNG files doesn't match the output gamma.
 *    If you have PNG files with no gamma information png_set_alpha_mode allows
 *    you to provide a default gamma, but it also sets the ouput gamma to the
 *    matching value.  If you know your PNG files have a gamma that doesn't
 *    match the output you can take advantage of the fact that
 *    png_set_alpha_mode always sets the output gamma but only sets the PNG
 *    default if it is not already set:
 *
 * png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB);
 * png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC);
 *    The first call sets both the default and the output gamma values, the
 *    second call overrides the output gamma without changing the default.  This
 *    is easier than achieving the same effect with png_set_gamma.  You must use
 *    PNG_ALPHA_PNG for the first call - internal checking in png_set_alpha will
 *    fire if more than one call to png_set_alpha_mode and png_set_background is
 *    made in the same read operation, however multiple calls with PNG_ALPHA_PNG
 *    are ignored.
 */

1408
#ifdef PNG_READ_STRIP_ALPHA_SUPPORTED
1409
PNG_EXPORT(36, void, png_set_strip_alpha, (png_structrp png_ptr));
1410
#endif
G
Guy Schalnat 已提交
1411

A
Andreas Dilger 已提交
1412 1413
#if defined(PNG_READ_SWAP_ALPHA_SUPPORTED) || \
    defined(PNG_WRITE_SWAP_ALPHA_SUPPORTED)
1414
PNG_EXPORT(37, void, png_set_swap_alpha, (png_structrp png_ptr));
1415
#endif
G
Guy Schalnat 已提交
1416

1417 1418
#if defined(PNG_READ_INVERT_ALPHA_SUPPORTED) || \
    defined(PNG_WRITE_INVERT_ALPHA_SUPPORTED)
1419
PNG_EXPORT(38, void, png_set_invert_alpha, (png_structrp png_ptr));
1420
#endif
1421

A
Andreas Dilger 已提交
1422
#if defined(PNG_READ_FILLER_SUPPORTED) || defined(PNG_WRITE_FILLER_SUPPORTED)
1423
/* Add a filler byte to 8-bit Gray or 24-bit RGB images. */
1424
PNG_EXPORT(39, void, png_set_filler, (png_structrp png_ptr, png_uint_32 filler,
1425
    int flags));
A
Andreas Dilger 已提交
1426
/* The values of the PNG_FILLER_ defines should NOT be changed */
1427 1428
#  define PNG_FILLER_BEFORE 0
#  define PNG_FILLER_AFTER 1
1429
/* Add an alpha byte to 8-bit Gray or 24-bit RGB images. */
1430
PNG_EXPORT(40, void, png_set_add_alpha, (png_structrp png_ptr,
1431
    png_uint_32 filler, int flags));
A
Andreas Dilger 已提交
1432
#endif /* PNG_READ_FILLER_SUPPORTED || PNG_WRITE_FILLER_SUPPORTED */
G
Guy Schalnat 已提交
1433

G
Guy Schalnat 已提交
1434
#if defined(PNG_READ_SWAP_SUPPORTED) || defined(PNG_WRITE_SWAP_SUPPORTED)
1435
/* Swap bytes in 16-bit depth files. */
1436
PNG_EXPORT(41, void, png_set_swap, (png_structrp png_ptr));
1437
#endif
G
Guy Schalnat 已提交
1438

G
Guy Schalnat 已提交
1439
#if defined(PNG_READ_PACK_SUPPORTED) || defined(PNG_WRITE_PACK_SUPPORTED)
1440
/* Use 1 byte per pixel in 1, 2, or 4-bit depth files. */
1441
PNG_EXPORT(42, void, png_set_packing, (png_structrp png_ptr));
1442
#endif
A
Andreas Dilger 已提交
1443

1444 1445
#if defined(PNG_READ_PACKSWAP_SUPPORTED) || \
    defined(PNG_WRITE_PACKSWAP_SUPPORTED)
A
Andreas Dilger 已提交
1446
/* Swap packing order of pixels in bytes. */
1447
PNG_EXPORT(43, void, png_set_packswap, (png_structrp png_ptr));
1448
#endif
G
Guy Schalnat 已提交
1449

G
Guy Schalnat 已提交
1450
#if defined(PNG_READ_SHIFT_SUPPORTED) || defined(PNG_WRITE_SHIFT_SUPPORTED)
G
Guy Schalnat 已提交
1451
/* Converts files to legal bit depths. */
1452
PNG_EXPORT(44, void, png_set_shift, (png_structrp png_ptr, png_const_color_8p
1453
    true_bits));
1454
#endif
G
Guy Schalnat 已提交
1455

G
Guy Schalnat 已提交
1456 1457
#if defined(PNG_READ_INTERLACING_SUPPORTED) || \
    defined(PNG_WRITE_INTERLACING_SUPPORTED)
G
[devel]  
Glenn Randers-Pehrson 已提交
1458
/* Have the code handle the interlacing.  Returns the number of passes.
1459 1460 1461 1462 1463
 * MUST be called before png_read_update_info or png_start_read_image,
 * otherwise it will not have the desired effect.  Note that it is still
 * necessary to call png_read_row or png_read_rows png_get_image_height
 * times for each pass.
*/
1464
PNG_EXPORT(45, int, png_set_interlace_handling, (png_structrp png_ptr));
1465
#endif
G
Guy Schalnat 已提交
1466

G
Guy Schalnat 已提交
1467
#if defined(PNG_READ_INVERT_SUPPORTED) || defined(PNG_WRITE_INVERT_SUPPORTED)
1468
/* Invert monochrome files */
1469
PNG_EXPORT(46, void, png_set_invert_mono, (png_structrp png_ptr));
1470
#endif
G
Guy Schalnat 已提交
1471

1472
#ifdef PNG_READ_BACKGROUND_SUPPORTED
1473
/* Handle alpha and tRNS by replacing with a background color.  Prior to
1474
 * libpng-1.5.4 this API must not be called before the PNG file header has been
1475
 * read.  Doing so will result in unexpected behavior and possible warnings or
1476
 * errors if the PNG file contains a bKGD chunk.
1477
 */
1478
PNG_FP_EXPORT(47, void, png_set_background, (png_structrp png_ptr,
1479
    png_const_color_16p background_color, int background_gamma_code,
1480
    int need_expand, double background_gamma))
1481
PNG_FIXED_EXPORT(215, void, png_set_background_fixed, (png_structrp png_ptr,
1482
    png_const_color_16p background_color, int background_gamma_code,
1483
    int need_expand, png_fixed_point background_gamma))
G
[devel]  
Glenn Randers-Pehrson 已提交
1484 1485
#endif
#ifdef PNG_READ_BACKGROUND_SUPPORTED
1486 1487 1488 1489
#  define PNG_BACKGROUND_GAMMA_UNKNOWN 0
#  define PNG_BACKGROUND_GAMMA_SCREEN  1
#  define PNG_BACKGROUND_GAMMA_FILE    2
#  define PNG_BACKGROUND_GAMMA_UNIQUE  3
1490
#endif
G
Guy Schalnat 已提交
1491

1492
#ifdef PNG_READ_SCALE_16_TO_8_SUPPORTED
1493
/* Scale a 16-bit depth file down to 8-bit, accurately. */
1494
PNG_EXPORT(229, void, png_set_scale_16, (png_structrp png_ptr));
1495
#endif
1496

1497 1498
#ifdef PNG_READ_STRIP_16_TO_8_SUPPORTED
#define PNG_READ_16_TO_8 SUPPORTED /* Name prior to 1.5.4 */
1499
/* Strip the second byte of information from a 16-bit depth file. */
1500
PNG_EXPORT(48, void, png_set_strip_16, (png_structrp png_ptr));
1501
#endif
G
Guy Schalnat 已提交
1502

1503 1504
#ifdef PNG_READ_QUANTIZE_SUPPORTED
/* Turn on quantizing, and reduce the palette to the number of colors
1505 1506
 * available.
 */
1507 1508 1509
PNG_EXPORT(49, void, png_set_quantize, (png_structrp png_ptr,
    png_colorp palette, int num_palette, int maximum_colors,
    png_const_uint_16p histogram, int full_quantize));
1510
#endif
G
Guy Schalnat 已提交
1511

1512
#ifdef PNG_READ_GAMMA_SUPPORTED
G
[devel]  
Glenn Randers-Pehrson 已提交
1513 1514 1515 1516 1517
/* The threshold on gamma processing is configurable but hard-wired into the
 * library.  The following is the floating point variant.
 */
#define PNG_GAMMA_THRESHOLD (PNG_GAMMA_THRESHOLD_FIXED*.00001)

1518
/* Handle gamma correction. Screen_gamma=(display_exponent).
1519
 * NOTE: this API simply sets the screen and file gamma values. It will
1520
 * therefore override the value for gamma in a PNG file if it is called after
1521 1522 1523 1524 1525 1526 1527
 * the file header has been read - use with care  - call before reading the PNG
 * file for best results!
 *
 * These routines accept the same gamma values as png_set_alpha_mode (described
 * above).  The PNG_GAMMA_ defines and PNG_DEFAULT_sRGB can be passed to either
 * API (floating point or fixed.)  Notice, however, that the 'file_gamma' value
 * is the inverse of a 'screen gamma' value.
1528
 */
1529
PNG_FP_EXPORT(50, void, png_set_gamma, (png_structrp png_ptr,
1530
    double screen_gamma, double override_file_gamma))
1531
PNG_FIXED_EXPORT(208, void, png_set_gamma_fixed, (png_structrp png_ptr,
1532
    png_fixed_point screen_gamma, png_fixed_point override_file_gamma))
1533
#endif
G
Guy Schalnat 已提交
1534

1535
#ifdef PNG_WRITE_FLUSH_SUPPORTED
G
Guy Schalnat 已提交
1536
/* Set how many lines between output flushes - 0 for no flushing */
1537
PNG_EXPORT(51, void, png_set_flush, (png_structrp png_ptr, int nrows));
G
Guy Schalnat 已提交
1538
/* Flush the current PNG output buffer */
1539
PNG_EXPORT(52, void, png_write_flush, (png_structrp png_ptr));
1540
#endif
G
Guy Schalnat 已提交
1541

1542
/* Optional update palette with requested transformations */
1543
PNG_EXPORT(53, void, png_start_read_image, (png_structrp png_ptr));
G
Guy Schalnat 已提交
1544

1545
/* Optional call to update the users info structure */
1546 1547
PNG_EXPORT(54, void, png_read_update_info, (png_structrp png_ptr,
    png_inforp info_ptr));
G
Guy Schalnat 已提交
1548

1549
#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
1550
/* Read one or more rows of image data. */
1551
PNG_EXPORT(55, void, png_read_rows, (png_structrp png_ptr, png_bytepp row,
1552
    png_bytepp display_row, png_uint_32 num_rows));
1553
#endif
G
Guy Schalnat 已提交
1554

1555
#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
1556
/* Read a row of data. */
1557
PNG_EXPORT(56, void, png_read_row, (png_structrp png_ptr, png_bytep row,
1558
    png_bytep display_row));
1559
#endif
G
Guy Schalnat 已提交
1560

1561
#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
1562
/* Read the whole image into memory at once. */
1563
PNG_EXPORT(57, void, png_read_image, (png_structrp png_ptr, png_bytepp image));
1564
#endif
G
Guy Schalnat 已提交
1565

1566
/* Write a row of image data */
1567 1568
PNG_EXPORT(58, void, png_write_row, (png_structrp png_ptr,
    png_const_bytep row));
G
Guy Schalnat 已提交
1569

1570 1571 1572
/* Write a few rows of image data: (*row) is not written; however, the type
 * is declared as writeable to maintain compatibility with previous versions
 * of libpng and to allow the 'display_row' array from read_rows to be passed
1573 1574
 * unchanged to write_rows.
 */
1575
PNG_EXPORT(59, void, png_write_rows, (png_structrp png_ptr, png_bytepp row,
1576
    png_uint_32 num_rows));
G
Guy Schalnat 已提交
1577

1578
/* Write the image data */
1579
PNG_EXPORT(60, void, png_write_image, (png_structrp png_ptr, png_bytepp image));
G
Guy Schalnat 已提交
1580

1581
/* Write the end of the PNG file. */
1582 1583
PNG_EXPORT(61, void, png_write_end, (png_structrp png_ptr,
    png_inforp info_ptr));
G
Guy Schalnat 已提交
1584

1585
#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
1586
/* Read the end of the PNG file. */
1587
PNG_EXPORT(62, void, png_read_end, (png_structrp png_ptr, png_inforp info_ptr));
1588
#endif
G
Guy Schalnat 已提交
1589

1590
/* Free any memory associated with the png_info_struct */
1591
PNG_EXPORT(63, void, png_destroy_info_struct, (png_const_structrp png_ptr,
1592
    png_infopp info_ptr_ptr));
G
Guy Schalnat 已提交
1593

1594
/* Free any memory associated with the png_struct and the png_info_structs */
1595
PNG_EXPORT(64, void, png_destroy_read_struct, (png_structpp png_ptr_ptr,
1596
    png_infopp info_ptr_ptr, png_infopp end_info_ptr_ptr));
G
Guy Schalnat 已提交
1597

1598
/* Free any memory associated with the png_struct and the png_info_structs */
1599
PNG_EXPORT(65, void, png_destroy_write_struct, (png_structpp png_ptr_ptr,
1600
    png_infopp info_ptr_ptr));
G
Guy Schalnat 已提交
1601

1602
/* Set the libpng method of handling chunk CRC errors */
1603
PNG_EXPORT(66, void, png_set_crc_action, (png_structrp png_ptr, int crit_action,
1604
    int ancil_action));
A
Andreas Dilger 已提交
1605

1606
/* Values for png_set_crc_action() say how to handle CRC errors in
A
Andreas Dilger 已提交
1607 1608
 * ancillary and critical chunks, and whether to use the data contained
 * therein.  Note that it is impossible to "discard" data in a critical
1609
 * chunk.  For versions prior to 0.90, the action was always error/quit,
A
Andreas Dilger 已提交
1610 1611 1612 1613
 * whereas in version 0.90 and later, the action for CRC errors in ancillary
 * chunks is warn/discard.  These values should NOT be changed.
 *
 *      value                       action:critical     action:ancillary
A
Andreas Dilger 已提交
1614 1615 1616 1617 1618 1619 1620 1621
 */
#define PNG_CRC_DEFAULT       0  /* error/quit          warn/discard data */
#define PNG_CRC_ERROR_QUIT    1  /* error/quit          error/quit        */
#define PNG_CRC_WARN_DISCARD  2  /* (INVALID)           warn/discard data */
#define PNG_CRC_WARN_USE      3  /* warn/use data       warn/use data     */
#define PNG_CRC_QUIET_USE     4  /* quiet/use data      quiet/use data    */
#define PNG_CRC_NO_CHANGE     5  /* use current value   use current value */

A
Andreas Dilger 已提交
1622 1623 1624 1625 1626
/* These functions give the user control over the scan-line filtering in
 * libpng and the compression methods used by zlib.  These functions are
 * mainly useful for testing, as the defaults should work with most users.
 * Those users who are tight on memory or want faster performance at the
 * expense of compression can modify them.  See the compression library
1627 1628
 * header file (zlib.h) for an explination of the compression functions.
 */
A
Andreas Dilger 已提交
1629

1630
/* Set the filtering method(s) used by libpng.  Currently, the only valid
1631 1632
 * value for "method" is 0.
 */
1633
PNG_EXPORT(67, void, png_set_filter, (png_structrp png_ptr, int method,
1634
    int filters));
G
Guy Schalnat 已提交
1635

A
Andreas Dilger 已提交
1636
/* Flags for png_set_filter() to say which filters to use.  The flags
A
Andreas Dilger 已提交
1637 1638 1639
 * are chosen so that they don't conflict with real filter types
 * below, in case they are supplied instead of the #defined constants.
 * These values should NOT be changed.
A
Andreas Dilger 已提交
1640 1641 1642 1643 1644 1645 1646 1647 1648 1649
 */
#define PNG_NO_FILTERS     0x00
#define PNG_FILTER_NONE    0x08
#define PNG_FILTER_SUB     0x10
#define PNG_FILTER_UP      0x20
#define PNG_FILTER_AVG     0x40
#define PNG_FILTER_PAETH   0x80
#define PNG_ALL_FILTERS (PNG_FILTER_NONE | PNG_FILTER_SUB | PNG_FILTER_UP | \
                         PNG_FILTER_AVG | PNG_FILTER_PAETH)

A
Andreas Dilger 已提交
1650 1651 1652 1653 1654 1655 1656 1657 1658 1659
/* Filter values (not flags) - used in pngwrite.c, pngwutil.c for now.
 * These defines should NOT be changed.
 */
#define PNG_FILTER_VALUE_NONE  0
#define PNG_FILTER_VALUE_SUB   1
#define PNG_FILTER_VALUE_UP    2
#define PNG_FILTER_VALUE_AVG   3
#define PNG_FILTER_VALUE_PAETH 4
#define PNG_FILTER_VALUE_LAST  5

1660
#ifdef PNG_WRITE_WEIGHTED_FILTER_SUPPORTED /* EXPERIMENTAL */
A
Andreas Dilger 已提交
1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688
/* The "heuristic_method" is given by one of the PNG_FILTER_HEURISTIC_
 * defines, either the default (minimum-sum-of-absolute-differences), or
 * the experimental method (weighted-minimum-sum-of-absolute-differences).
 *
 * Weights are factors >= 1.0, indicating how important it is to keep the
 * filter type consistent between rows.  Larger numbers mean the current
 * filter is that many times as likely to be the same as the "num_weights"
 * previous filters.  This is cumulative for each previous row with a weight.
 * There needs to be "num_weights" values in "filter_weights", or it can be
 * NULL if the weights aren't being specified.  Weights have no influence on
 * the selection of the first row filter.  Well chosen weights can (in theory)
 * improve the compression for a given image.
 *
 * Costs are factors >= 1.0 indicating the relative decoding costs of a
 * filter type.  Higher costs indicate more decoding expense, and are
 * therefore less likely to be selected over a filter with lower computational
 * costs.  There needs to be a value in "filter_costs" for each valid filter
 * type (given by PNG_FILTER_VALUE_LAST), or it can be NULL if you aren't
 * setting the costs.  Costs try to improve the speed of decompression without
 * unduly increasing the compressed image size.
 *
 * A negative weight or cost indicates the default value is to be used, and
 * values in the range [0.0, 1.0) indicate the value is to remain unchanged.
 * The default values for both weights and costs are currently 1.0, but may
 * change if good general weighting/cost heuristics can be found.  If both
 * the weights and costs are set to 1.0, this degenerates the WEIGHTED method
 * to the UNWEIGHTED method, but with added encoding time/computation.
 */
1689
PNG_FP_EXPORT(68, void, png_set_filter_heuristics, (png_structrp png_ptr,
1690
    int heuristic_method, int num_weights, png_const_doublep filter_weights,
1691
    png_const_doublep filter_costs))
1692
PNG_FIXED_EXPORT(209, void, png_set_filter_heuristics_fixed,
1693
    (png_structrp png_ptr, int heuristic_method, int num_weights,
1694
    png_const_fixed_point_p filter_weights,
1695
    png_const_fixed_point_p filter_costs))
A
Andreas Dilger 已提交
1696 1697 1698 1699 1700 1701 1702 1703 1704 1705
#endif /*  PNG_WRITE_WEIGHTED_FILTER_SUPPORTED */

/* Heuristic used for row filter selection.  These defines should NOT be
 * changed.
 */
#define PNG_FILTER_HEURISTIC_DEFAULT    0  /* Currently "UNWEIGHTED" */
#define PNG_FILTER_HEURISTIC_UNWEIGHTED 1  /* Used by libpng < 0.95 */
#define PNG_FILTER_HEURISTIC_WEIGHTED   2  /* Experimental feature */
#define PNG_FILTER_HEURISTIC_LAST       3  /* Not a valid value */

1706
#ifdef PNG_WRITE_SUPPORTED
A
Andreas Dilger 已提交
1707 1708 1709 1710
/* Set the library compression level.  Currently, valid values range from
 * 0 - 9, corresponding directly to the zlib compression levels 0 - 9
 * (0 - no compression, 9 - "maximal" compression).  Note that tests have
 * shown that zlib compression levels 3-6 usually perform as well as level 9
1711
 * for PNG images, and do considerably fewer caclulations.  In the future,
A
Andreas Dilger 已提交
1712 1713
 * these values may not correspond directly to the zlib compression levels.
 */
1714
PNG_EXPORT(69, void, png_set_compression_level, (png_structrp png_ptr,
1715
    int level));
G
Guy Schalnat 已提交
1716

1717
PNG_EXPORT(70, void, png_set_compression_mem_level, (png_structrp png_ptr,
1718
    int mem_level));
G
Guy Schalnat 已提交
1719

1720
PNG_EXPORT(71, void, png_set_compression_strategy, (png_structrp png_ptr,
1721
    int strategy));
G
Guy Schalnat 已提交
1722

1723 1724 1725
/* If PNG_WRITE_OPTIMIZE_CMF_SUPPORTED is defined, libpng will use a
 * smaller value of window_bits if it can do so safely.
 */
1726
PNG_EXPORT(72, void, png_set_compression_window_bits, (png_structrp png_ptr,
1727
    int window_bits));
G
Guy Schalnat 已提交
1728

1729
PNG_EXPORT(73, void, png_set_compression_method, (png_structrp png_ptr,
1730
    int method));
1731
#endif
G
Guy Schalnat 已提交
1732

1733
#ifdef PNG_WRITE_CUSTOMIZE_ZTXT_COMPRESSION_SUPPORTED
1734
/* Also set zlib parameters for compressing non-IDAT chunks */
1735
PNG_EXPORT(222, void, png_set_text_compression_level, (png_structrp png_ptr,
1736
    int level));
1737

1738
PNG_EXPORT(223, void, png_set_text_compression_mem_level, (png_structrp png_ptr,
1739 1740
    int mem_level));

1741
PNG_EXPORT(224, void, png_set_text_compression_strategy, (png_structrp png_ptr,
1742 1743
    int strategy));

1744 1745 1746
/* If PNG_WRITE_OPTIMIZE_CMF_SUPPORTED is defined, libpng will use a
 * smaller value of window_bits if it can do so safely.
 */
1747
PNG_EXPORT(225, void, png_set_text_compression_window_bits,
1748
    (png_structrp png_ptr, int window_bits));
1749

1750
PNG_EXPORT(226, void, png_set_text_compression_method, (png_structrp png_ptr,
1751
    int method));
1752
#endif /* PNG_WRITE_CUSTOMIZE_ZTXT_COMPRESSION_SUPPORTED */
1753

G
Guy Schalnat 已提交
1754
/* These next functions are called for input/output, memory, and error
1755
 * handling.  They are in the file pngrio.c, pngwio.c, and pngerror.c,
A
Andreas Dilger 已提交
1756 1757 1758
 * and call standard C I/O routines such as fread(), fwrite(), and
 * fprintf().  These functions can be made to use other I/O routines
 * at run time for those applications that need to handle I/O in a
1759
 * different manner by calling png_set_???_fn().  See libpng-manual.txt for
A
Andreas Dilger 已提交
1760 1761
 * more information.
 */
G
Guy Schalnat 已提交
1762

1763
#ifdef PNG_STDIO_SUPPORTED
A
Andreas Dilger 已提交
1764
/* Initialize the input/output for the PNG file to the default functions. */
1765
PNG_EXPORT(74, void, png_init_io, (png_structrp png_ptr, png_FILE_p fp));
1766
#endif
G
Guy Schalnat 已提交
1767

A
Andreas Dilger 已提交
1768
/* Replace the (error and abort), and warning functions with user
A
Andreas Dilger 已提交
1769 1770 1771 1772 1773 1774
 * supplied functions.  If no messages are to be printed you must still
 * write and use replacement functions. The replacement error_fn should
 * still do a longjmp to the last setjmp location if you are using this
 * method of error handling.  If error_fn or warning_fn is NULL, the
 * default function will be used.
 */
1775

1776
PNG_EXPORT(75, void, png_set_error_fn, (png_structrp png_ptr,
1777
    png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr warning_fn));
G
Guy Schalnat 已提交
1778

G
Guy Schalnat 已提交
1779
/* Return the user pointer associated with the error functions */
1780
PNG_EXPORT(76, png_voidp, png_get_error_ptr, (png_const_structrp png_ptr));
G
Guy Schalnat 已提交
1781 1782

/* Replace the default data output functions with a user supplied one(s).
A
Andreas Dilger 已提交
1783 1784 1785
 * If buffered output is not used, then output_flush_fn can be set to NULL.
 * If PNG_WRITE_FLUSH_SUPPORTED is not defined at libpng compile time
 * output_flush_fn will be ignored (and thus can be NULL).
1786 1787 1788 1789 1790
 * It is probably a mistake to use NULL for output_flush_fn if
 * write_data_fn is not also NULL unless you have built libpng with
 * PNG_WRITE_FLUSH_SUPPORTED undefined, because in this case libpng's
 * default flush function, which uses the standard *FILE structure, will
 * be used.
A
Andreas Dilger 已提交
1791
 */
1792
PNG_EXPORT(77, void, png_set_write_fn, (png_structrp png_ptr, png_voidp io_ptr,
1793
    png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn));
G
Guy Schalnat 已提交
1794 1795

/* Replace the default data input function with a user supplied one. */
1796
PNG_EXPORT(78, void, png_set_read_fn, (png_structrp png_ptr, png_voidp io_ptr,
1797
    png_rw_ptr read_data_fn));
G
Guy Schalnat 已提交
1798 1799

/* Return the user pointer associated with the I/O functions */
1800
PNG_EXPORT(79, png_voidp, png_get_io_ptr, (png_const_structrp png_ptr));
G
Guy Schalnat 已提交
1801

1802
PNG_EXPORT(80, void, png_set_read_status_fn, (png_structrp png_ptr,
1803
    png_read_status_ptr read_row_fn));
1804

1805
PNG_EXPORT(81, void, png_set_write_status_fn, (png_structrp png_ptr,
1806
    png_write_status_ptr write_row_fn));
1807

1808 1809
#ifdef PNG_USER_MEM_SUPPORTED
/* Replace the default memory allocation functions with user supplied one(s). */
1810
PNG_EXPORT(82, void, png_set_mem_fn, (png_structrp png_ptr, png_voidp mem_ptr,
1811
    png_malloc_ptr malloc_fn, png_free_ptr free_fn));
1812
/* Return the user pointer associated with the memory functions */
1813
PNG_EXPORT(83, png_voidp, png_get_mem_ptr, (png_const_structrp png_ptr));
1814
#endif
1815

1816
#ifdef PNG_READ_USER_TRANSFORM_SUPPORTED
1817
PNG_EXPORT(84, void, png_set_read_user_transform_fn, (png_structrp png_ptr,
1818
    png_user_transform_ptr read_user_transform_fn));
1819 1820
#endif

1821
#ifdef PNG_WRITE_USER_TRANSFORM_SUPPORTED
1822
PNG_EXPORT(85, void, png_set_write_user_transform_fn, (png_structrp png_ptr,
1823
    png_user_transform_ptr write_user_transform_fn));
1824 1825
#endif

1826
#ifdef PNG_USER_TRANSFORM_PTR_SUPPORTED
1827
PNG_EXPORT(86, void, png_set_user_transform_info, (png_structrp png_ptr,
1828
    png_voidp user_transform_ptr, int user_transform_depth,
1829
    int user_transform_channels));
1830
/* Return the user pointer associated with the user transform functions */
1831
PNG_EXPORT(87, png_voidp, png_get_user_transform_ptr,
1832
    (png_const_structrp png_ptr));
1833 1834 1835 1836 1837 1838
#endif

#ifdef PNG_USER_TRANSFORM_INFO_SUPPORTED
/* Return information about the row currently being processed.  Note that these
 * APIs do not fail but will return unexpected results if called outside a user
 * transform callback.  Also note that when transforming an interlaced image the
1839 1840 1841
 * row number is the row number within the sub-image of the interlace pass, so
 * the value will increase to the height of the sub-image (not the full image)
 * then reset to 0 for the next pass.
1842
 *
1843 1844 1845
 * Use PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
 * find the output pixel (x,y) given an interlaced sub-image pixel
 * (row,col,pass).  (See below for these macros.)
1846
 */
1847 1848
PNG_EXPORT(217, png_uint_32, png_get_current_row_number, (png_const_structrp));
PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structrp));
1849 1850
#endif

1851
#ifdef PNG_READ_USER_CHUNKS_SUPPORTED
1852
/* This callback is called only for *unknown* chunks.  If
1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863
 * PNG_HANDLE_AS_UNKNOWN_SUPPORTED is set then it is possible to set known
 * chunks to be treated as unknown, however in this case the callback must do
 * any processing required by the chunk (e.g. by calling the appropriate
 * png_set_ APIs.)
 *
 * There is no write support - on write, by default, all the chunks in the
 * 'unknown' list are written in the specified position.
 *
 * The integer return from the callback function is interpreted thus:
 *
 * negative: An error occured, png_chunk_error will be called.
1864 1865
 *     zero: The chunk was not handled, the chunk will be saved. A critical
 *           chunk will cause an error at this point unless it is to be saved.
1866
 * positive: The chunk was handled, libpng will ignore/discard it.
1867 1868 1869
 *
 * See "INTERACTION WTIH USER CHUNK CALLBACKS" below for important notes about
 * how this behavior will change in libpng 1.7
1870
 */
1871
PNG_EXPORT(88, void, png_set_read_user_chunk_fn, (png_structrp png_ptr,
1872
    png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn));
1873 1874 1875
#endif

#ifdef PNG_USER_CHUNKS_SUPPORTED
1876
PNG_EXPORT(89, png_voidp, png_get_user_chunk_ptr, (png_const_structrp png_ptr));
1877 1878
#endif

G
Guy Schalnat 已提交
1879
#ifdef PNG_PROGRESSIVE_READ_SUPPORTED
A
Andreas Dilger 已提交
1880 1881 1882
/* Sets the function callbacks for the push reader, and a pointer to a
 * user-defined structure available to the callback functions.
 */
1883
PNG_EXPORT(90, void, png_set_progressive_read_fn, (png_structrp png_ptr,
1884
    png_voidp progressive_ptr, png_progressive_info_ptr info_fn,
1885
    png_progressive_row_ptr row_fn, png_progressive_end_ptr end_fn));
G
Guy Schalnat 已提交
1886

1887
/* Returns the user pointer associated with the push read functions */
1888 1889
PNG_EXPORT(91, png_voidp, png_get_progressive_ptr,
    (png_const_structrp png_ptr));
A
Andreas Dilger 已提交
1890

1891
/* Function to be called when data becomes available */
1892 1893
PNG_EXPORT(92, void, png_process_data, (png_structrp png_ptr,
    png_inforp info_ptr, png_bytep buffer, png_size_t buffer_size));
A
Andreas Dilger 已提交
1894

1895 1896 1897 1898 1899 1900 1901
/* A function which may be called *only* within png_process_data to stop the
 * processing of any more data.  The function returns the number of bytes
 * remaining, excluding any that libpng has cached internally.  A subsequent
 * call to png_process_data must supply these bytes again.  If the argument
 * 'save' is set to true the routine will first save all the pending data and
 * will always return 0.
 */
1902
PNG_EXPORT(219, png_size_t, png_process_data_pause, (png_structrp, int save));
1903 1904 1905 1906 1907 1908 1909

/* A function which may be called *only* outside (after) a call to
 * png_process_data.  It returns the number of bytes of data to skip in the
 * input.  Normally it will return 0, but if it returns a non-zero value the
 * application must skip than number of bytes of input data and pass the
 * following data to the next call to png_process_data.
 */
1910
PNG_EXPORT(220, png_uint_32, png_process_data_skip, (png_structrp));
1911

1912
#ifdef PNG_READ_INTERLACING_SUPPORTED
1913 1914 1915 1916
/* Function that combines rows.  'new_row' is a flag that should come from
 * the callback and be non-NULL if anything needs to be done; the library
 * stores its own version of the new data internally and ignores the passed
 * in value.
A
Andreas Dilger 已提交
1917
 */
1918
PNG_EXPORT(93, void, png_progressive_combine_row, (png_const_structrp png_ptr,
1919
    png_bytep old_row, png_const_bytep new_row));
1920
#endif /* PNG_READ_INTERLACING_SUPPORTED */
G
Guy Schalnat 已提交
1921
#endif /* PNG_PROGRESSIVE_READ_SUPPORTED */
G
Guy Schalnat 已提交
1922

1923
PNG_EXPORTA(94, png_voidp, png_malloc, (png_const_structrp png_ptr,
1924
    png_alloc_size_t size), PNG_ALLOCATED);
1925
/* Added at libpng version 1.4.0 */
1926
PNG_EXPORTA(95, png_voidp, png_calloc, (png_const_structrp png_ptr,
1927
    png_alloc_size_t size), PNG_ALLOCATED);
G
Guy Schalnat 已提交
1928

1929
/* Added at libpng version 1.2.4 */
1930
PNG_EXPORTA(96, png_voidp, png_malloc_warn, (png_const_structrp png_ptr,
1931
    png_alloc_size_t size), PNG_ALLOCATED);
1932

1933
/* Frees a pointer allocated by png_malloc() */
1934
PNG_EXPORT(97, void, png_free, (png_const_structrp png_ptr, png_voidp ptr));
A
Andreas Dilger 已提交
1935

1936
/* Free data that was allocated internally */
1937 1938
PNG_EXPORT(98, void, png_free_data, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_uint_32 free_me, int num));
1939

1940
/* Reassign responsibility for freeing existing data, whether allocated
1941 1942
 * by libpng or by the application; this works on the png_info structure passed
 * in, it does not change the state for other png_info structures.
1943 1944 1945
 *
 * It is unlikely that this function works correctly as of 1.6.0 and using it
 * may result either in memory leaks or double free of allocated data.
1946
 */
1947 1948
PNG_EXPORTA(99, void, png_data_freer, (png_const_structrp png_ptr,
    png_inforp info_ptr, int freer, png_uint_32 mask), PNG_DEPRECATED);
1949

1950
/* Assignments for png_data_freer */
1951 1952 1953 1954
#define PNG_DESTROY_WILL_FREE_DATA 1
#define PNG_SET_WILL_FREE_DATA 1
#define PNG_USER_WILL_FREE_DATA 2
/* Flags for png_ptr->free_me and info_ptr->free_me */
1955 1956 1957 1958
#define PNG_FREE_HIST 0x0008
#define PNG_FREE_ICCP 0x0010
#define PNG_FREE_SPLT 0x0020
#define PNG_FREE_ROWS 0x0040
1959 1960
#define PNG_FREE_PCAL 0x0080
#define PNG_FREE_SCAL 0x0100
1961 1962 1963 1964
#ifdef PNG_STORE_UNKNOWN_CHUNKS_SUPPORTED
#  define PNG_FREE_UNKN 0x0200
#endif
/*      PNG_FREE_LIST 0x0400    removed in 1.6.0 because it is ignored */
1965 1966 1967
#define PNG_FREE_PLTE 0x1000
#define PNG_FREE_TRNS 0x2000
#define PNG_FREE_TEXT 0x4000
1968
#define PNG_FREE_ALL  0x7fff
1969
#define PNG_FREE_MUL  0x4220 /* PNG_FREE_SPLT|PNG_FREE_TEXT|PNG_FREE_UNKN */
1970

1971
#ifdef PNG_USER_MEM_SUPPORTED
1972
PNG_EXPORTA(100, png_voidp, png_malloc_default, (png_const_structrp png_ptr,
1973
    png_alloc_size_t size), PNG_ALLOCATED PNG_DEPRECATED);
1974
PNG_EXPORTA(101, void, png_free_default, (png_const_structrp png_ptr,
1975
    png_voidp ptr), PNG_DEPRECATED);
1976
#endif
1977

1978
#ifdef PNG_ERROR_TEXT_SUPPORTED
A
Andreas Dilger 已提交
1979
/* Fatal error in PNG image of libpng - can't continue */
1980
PNG_EXPORTA(102, void, png_error, (png_const_structrp png_ptr,
1981
    png_const_charp error_message), PNG_NORETURN);
G
Guy Schalnat 已提交
1982

1983
/* The same, but the chunk name is prepended to the error string. */
1984
PNG_EXPORTA(103, void, png_chunk_error, (png_const_structrp png_ptr,
1985
    png_const_charp error_message), PNG_NORETURN);
1986

1987 1988
#else
/* Fatal error in PNG image of libpng - can't continue */
1989
PNG_EXPORTA(104, void, png_err, (png_const_structrp png_ptr), PNG_NORETURN);
1990 1991
#endif

1992
#ifdef PNG_WARNINGS_SUPPORTED
G
Guy Schalnat 已提交
1993
/* Non-fatal error in libpng.  Can continue, but may have a problem. */
1994
PNG_EXPORT(105, void, png_warning, (png_const_structrp png_ptr,
1995
    png_const_charp warning_message));
A
Andreas Dilger 已提交
1996

1997
/* Non-fatal error in libpng, chunk name is prepended to message. */
1998
PNG_EXPORT(106, void, png_chunk_warning, (png_const_structrp png_ptr,
1999
    png_const_charp warning_message));
2000
#endif
2001

2002 2003 2004
#ifdef PNG_BENIGN_ERRORS_SUPPORTED
/* Benign error in libpng.  Can continue, but may have a problem.
 * User can choose whether to handle as a fatal error or as a warning. */
2005
PNG_EXPORT(107, void, png_benign_error, (png_const_structrp png_ptr,
2006
    png_const_charp warning_message));
2007

2008 2009
#ifdef PNG_READ_SUPPORTED
/* Same, chunk name is prepended to message (only during read) */
2010
PNG_EXPORT(108, void, png_chunk_benign_error, (png_const_structrp png_ptr,
2011
    png_const_charp warning_message));
2012
#endif
2013

2014
PNG_EXPORT(109, void, png_set_benign_errors,
2015
    (png_structrp png_ptr, int allowed));
2016 2017 2018 2019 2020 2021 2022 2023
#else
#  ifdef PNG_ALLOW_BENIGN_ERRORS
#    define png_benign_error png_warning
#    define png_chunk_benign_error png_chunk_warning
#  else
#    define png_benign_error png_error
#    define png_chunk_benign_error png_chunk_error
#  endif
2024 2025
#endif

A
Andreas Dilger 已提交
2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037
/* The png_set_<chunk> functions are for storing values in the png_info_struct.
 * Similarly, the png_get_<chunk> calls are used to read values from the
 * png_info_struct, either storing the parameters in the passed variables, or
 * setting pointers into the png_info_struct where the data is stored.  The
 * png_get_<chunk> functions return a non-zero value if the data was available
 * in info_ptr, or return zero and do not change any of the parameters if the
 * data was not available.
 *
 * These functions should be used instead of directly accessing png_info
 * to avoid problems with future changes in the size and internal layout of
 * png_info_struct.
 */
2038
/* Returns "flag" if chunk data is valid in info_ptr. */
2039 2040
PNG_EXPORT(110, png_uint_32, png_get_valid, (png_const_structrp png_ptr,
    png_const_inforp info_ptr, png_uint_32 flag));
A
Andreas Dilger 已提交
2041

2042
/* Returns number of bytes needed to hold a transformed row. */
2043 2044
PNG_EXPORT(111, png_size_t, png_get_rowbytes, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
A
Andreas Dilger 已提交
2045

2046
#ifdef PNG_INFO_IMAGE_SUPPORTED
2047
/* Returns row_pointers, which is an array of pointers to scanlines that was
2048 2049
 * returned from png_read_png().
 */
2050 2051
PNG_EXPORT(112, png_bytepp, png_get_rows, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2052

2053
/* Set row_pointers, which is an array of pointers to scanlines for use
2054 2055
 * by png_write_png().
 */
2056 2057
PNG_EXPORT(113, void, png_set_rows, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_bytepp row_pointers));
2058 2059
#endif

2060
/* Returns number of color channels in image. */
2061 2062
PNG_EXPORT(114, png_byte, png_get_channels, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
A
Andreas Dilger 已提交
2063

2064 2065
#ifdef PNG_EASY_ACCESS_SUPPORTED
/* Returns image width in pixels. */
2066 2067
PNG_EXPORT(115, png_uint_32, png_get_image_width, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2068 2069

/* Returns image height in pixels. */
2070 2071
PNG_EXPORT(116, png_uint_32, png_get_image_height, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2072 2073

/* Returns image bit_depth. */
2074 2075
PNG_EXPORT(117, png_byte, png_get_bit_depth, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2076 2077

/* Returns image color_type. */
2078 2079
PNG_EXPORT(118, png_byte, png_get_color_type, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2080 2081

/* Returns image filter_type. */
2082 2083
PNG_EXPORT(119, png_byte, png_get_filter_type, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2084 2085

/* Returns image interlace_type. */
2086 2087
PNG_EXPORT(120, png_byte, png_get_interlace_type, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2088 2089

/* Returns image compression_type. */
2090 2091
PNG_EXPORT(121, png_byte, png_get_compression_type, (png_const_structrp png_ptr,
    png_const_inforp info_ptr));
2092 2093

/* Returns image resolution in pixels per meter, from pHYs chunk data. */
2094
PNG_EXPORT(122, png_uint_32, png_get_pixels_per_meter,
2095
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2096
PNG_EXPORT(123, png_uint_32, png_get_x_pixels_per_meter,
2097
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2098
PNG_EXPORT(124, png_uint_32, png_get_y_pixels_per_meter,
2099
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2100 2101

/* Returns pixel aspect ratio, computed from pHYs chunk data.  */
2102
PNG_FP_EXPORT(125, float, png_get_pixel_aspect_ratio,
2103
    (png_const_structrp png_ptr, png_const_inforp info_ptr))
2104
PNG_FIXED_EXPORT(210, png_fixed_point, png_get_pixel_aspect_ratio_fixed,
2105
    (png_const_structrp png_ptr, png_const_inforp info_ptr))
2106 2107

/* Returns image x, y offset in pixels or microns, from oFFs chunk data. */
2108 2109 2110 2111
PNG_EXPORT(126, png_int_32, png_get_x_offset_pixels,
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
PNG_EXPORT(127, png_int_32, png_get_y_offset_pixels,
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2112
PNG_EXPORT(128, png_int_32, png_get_x_offset_microns,
2113
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2114
PNG_EXPORT(129, png_int_32, png_get_y_offset_microns,
2115
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2116 2117 2118

#endif /* PNG_EASY_ACCESS_SUPPORTED */

2119
#ifdef PNG_READ_SUPPORTED
A
Andreas Dilger 已提交
2120
/* Returns pointer to signature string read from PNG header */
2121
PNG_EXPORT(130, png_const_bytep, png_get_signature, (png_const_structrp png_ptr,
2122
    png_const_inforp info_ptr));
2123
#endif
A
Andreas Dilger 已提交
2124

2125
#ifdef PNG_bKGD_SUPPORTED
2126 2127
PNG_EXPORT(131, png_uint_32, png_get_bKGD, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_color_16p *background));
2128
#endif
A
Andreas Dilger 已提交
2129

2130
#ifdef PNG_bKGD_SUPPORTED
2131 2132
PNG_EXPORT(132, void, png_set_bKGD, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_color_16p background));
2133
#endif
A
Andreas Dilger 已提交
2134

2135
#ifdef PNG_cHRM_SUPPORTED
2136
PNG_FP_EXPORT(133, png_uint_32, png_get_cHRM, (png_const_structrp png_ptr,
2137
    png_const_inforp info_ptr, double *white_x, double *white_y, double *red_x,
2138
    double *red_y, double *green_x, double *green_y, double *blue_x,
2139
    double *blue_y))
2140 2141
PNG_FP_EXPORT(230, png_uint_32, png_get_cHRM_XYZ, (png_const_structrp png_ptr,
    png_const_inforp info_ptr, double *red_X, double *red_Y, double *red_Z,
2142
    double *green_X, double *green_Y, double *green_Z, double *blue_X,
2143
    double *blue_Y, double *blue_Z))
2144
PNG_FIXED_EXPORT(134, png_uint_32, png_get_cHRM_fixed,
2145
    (png_const_structrp png_ptr, png_const_inforp info_ptr,
2146 2147 2148
    png_fixed_point *int_white_x, png_fixed_point *int_white_y,
    png_fixed_point *int_red_x, png_fixed_point *int_red_y,
    png_fixed_point *int_green_x, png_fixed_point *int_green_y,
2149
    png_fixed_point *int_blue_x, png_fixed_point *int_blue_y))
2150
PNG_FIXED_EXPORT(231, png_uint_32, png_get_cHRM_XYZ_fixed,
2151
    (png_const_structrp png_ptr, png_const_inforp info_ptr,
2152 2153 2154 2155
    png_fixed_point *int_red_X, png_fixed_point *int_red_Y,
    png_fixed_point *int_red_Z, png_fixed_point *int_green_X,
    png_fixed_point *int_green_Y, png_fixed_point *int_green_Z,
    png_fixed_point *int_blue_X, png_fixed_point *int_blue_Y,
2156
    png_fixed_point *int_blue_Z))
2157
#endif
A
Andreas Dilger 已提交
2158

2159
#ifdef PNG_cHRM_SUPPORTED
2160 2161
PNG_FP_EXPORT(135, void, png_set_cHRM, (png_const_structrp png_ptr,
    png_inforp info_ptr,
2162
    double white_x, double white_y, double red_x, double red_y, double green_x,
2163
    double green_y, double blue_x, double blue_y))
2164
PNG_FP_EXPORT(232, void, png_set_cHRM_XYZ, (png_const_structrp png_ptr,
2165
    png_inforp info_ptr, double red_X, double red_Y, double red_Z,
2166
    double green_X, double green_Y, double green_Z, double blue_X,
2167
    double blue_Y, double blue_Z))
2168
PNG_FIXED_EXPORT(136, void, png_set_cHRM_fixed, (png_const_structrp png_ptr,
2169
    png_inforp info_ptr, png_fixed_point int_white_x,
2170 2171 2172
    png_fixed_point int_white_y, png_fixed_point int_red_x,
    png_fixed_point int_red_y, png_fixed_point int_green_x,
    png_fixed_point int_green_y, png_fixed_point int_blue_x,
2173
    png_fixed_point int_blue_y))
2174
PNG_FIXED_EXPORT(233, void, png_set_cHRM_XYZ_fixed, (png_const_structrp png_ptr,
2175
    png_inforp info_ptr, png_fixed_point int_red_X, png_fixed_point int_red_Y,
2176 2177 2178
    png_fixed_point int_red_Z, png_fixed_point int_green_X,
    png_fixed_point int_green_Y, png_fixed_point int_green_Z,
    png_fixed_point int_blue_X, png_fixed_point int_blue_Y,
2179
    png_fixed_point int_blue_Z))
2180
#endif
A
Andreas Dilger 已提交
2181

2182
#ifdef PNG_gAMA_SUPPORTED
2183
PNG_FP_EXPORT(137, png_uint_32, png_get_gAMA, (png_const_structrp png_ptr,
2184
    png_const_inforp info_ptr, double *file_gamma))
2185
PNG_FIXED_EXPORT(138, png_uint_32, png_get_gAMA_fixed,
2186
    (png_const_structrp png_ptr, png_const_inforp info_ptr,
2187
    png_fixed_point *int_file_gamma))
2188
#endif
G
Guy Schalnat 已提交
2189

2190
#ifdef PNG_gAMA_SUPPORTED
2191
PNG_FP_EXPORT(139, void, png_set_gAMA, (png_const_structrp png_ptr,
2192
    png_inforp info_ptr, double file_gamma))
2193
PNG_FIXED_EXPORT(140, void, png_set_gAMA_fixed, (png_const_structrp png_ptr,
2194
    png_inforp info_ptr, png_fixed_point int_file_gamma))
2195
#endif
A
Andreas Dilger 已提交
2196

2197
#ifdef PNG_hIST_SUPPORTED
2198
PNG_EXPORT(141, png_uint_32, png_get_hIST, (png_const_structrp png_ptr,
2199
    png_inforp info_ptr, png_uint_16p *hist));
2200
#endif
A
Andreas Dilger 已提交
2201

2202
#ifdef PNG_hIST_SUPPORTED
2203 2204
PNG_EXPORT(142, void, png_set_hIST, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_uint_16p hist));
2205
#endif
A
Andreas Dilger 已提交
2206

2207
PNG_EXPORT(143, png_uint_32, png_get_IHDR, (png_const_structrp png_ptr,
2208
    png_const_inforp info_ptr, png_uint_32 *width, png_uint_32 *height,
2209 2210
    int *bit_depth, int *color_type, int *interlace_method,
    int *compression_method, int *filter_method));
2211

2212 2213 2214 2215
PNG_EXPORT(144, void, png_set_IHDR, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_uint_32 width, png_uint_32 height, int bit_depth,
    int color_type, int interlace_method, int compression_method,
    int filter_method));
A
Andreas Dilger 已提交
2216

2217
#ifdef PNG_oFFs_SUPPORTED
2218 2219
PNG_EXPORT(145, png_uint_32, png_get_oFFs, (png_const_structrp png_ptr,
   png_const_inforp info_ptr, png_int_32 *offset_x, png_int_32 *offset_y,
2220
   int *unit_type));
2221
#endif
A
Andreas Dilger 已提交
2222

2223
#ifdef PNG_oFFs_SUPPORTED
2224 2225 2226
PNG_EXPORT(146, void, png_set_oFFs, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_int_32 offset_x, png_int_32 offset_y,
    int unit_type));
2227
#endif
A
Andreas Dilger 已提交
2228

2229
#ifdef PNG_pCAL_SUPPORTED
2230
PNG_EXPORT(147, png_uint_32, png_get_pCAL, (png_const_structrp png_ptr,
2231
    png_inforp info_ptr, png_charp *purpose, png_int_32 *X0,
2232 2233
    png_int_32 *X1, int *type, int *nparams, png_charp *units,
    png_charpp *params));
2234
#endif
A
Andreas Dilger 已提交
2235

2236
#ifdef PNG_pCAL_SUPPORTED
2237 2238 2239
PNG_EXPORT(148, void, png_set_pCAL, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_charp purpose, png_int_32 X0, png_int_32 X1,
    int type, int nparams, png_const_charp units, png_charpp params));
2240 2241
#endif

2242
#ifdef PNG_pHYs_SUPPORTED
2243 2244
PNG_EXPORT(149, png_uint_32, png_get_pHYs, (png_const_structrp png_ptr,
    png_const_inforp info_ptr, png_uint_32 *res_x, png_uint_32 *res_y,
2245
    int *unit_type));
2246
#endif
A
Andreas Dilger 已提交
2247

2248
#ifdef PNG_pHYs_SUPPORTED
2249 2250
PNG_EXPORT(150, void, png_set_pHYs, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_uint_32 res_x, png_uint_32 res_y, int unit_type));
2251
#endif
A
Andreas Dilger 已提交
2252

2253
PNG_EXPORT(151, png_uint_32, png_get_PLTE, (png_const_structrp png_ptr,
2254
   png_inforp info_ptr, png_colorp *palette, int *num_palette));
A
Andreas Dilger 已提交
2255

2256 2257
PNG_EXPORT(152, void, png_set_PLTE, (png_structrp png_ptr,
    png_inforp info_ptr, png_const_colorp palette, int num_palette));
A
Andreas Dilger 已提交
2258

2259
#ifdef PNG_sBIT_SUPPORTED
2260 2261
PNG_EXPORT(153, png_uint_32, png_get_sBIT, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_color_8p *sig_bit));
2262
#endif
A
Andreas Dilger 已提交
2263

2264
#ifdef PNG_sBIT_SUPPORTED
2265 2266
PNG_EXPORT(154, void, png_set_sBIT, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_color_8p sig_bit));
2267
#endif
A
Andreas Dilger 已提交
2268

2269
#ifdef PNG_sRGB_SUPPORTED
2270 2271
PNG_EXPORT(155, png_uint_32, png_get_sRGB, (png_const_structrp png_ptr,
    png_const_inforp info_ptr, int *file_srgb_intent));
2272
#endif
2273

2274
#ifdef PNG_sRGB_SUPPORTED
2275 2276 2277
PNG_EXPORT(156, void, png_set_sRGB, (png_const_structrp png_ptr,
    png_inforp info_ptr, int srgb_intent));
PNG_EXPORT(157, void, png_set_sRGB_gAMA_and_cHRM, (png_const_structrp png_ptr,
2278
    png_inforp info_ptr, int srgb_intent));
2279 2280
#endif

2281
#ifdef PNG_iCCP_SUPPORTED
2282
PNG_EXPORT(158, png_uint_32, png_get_iCCP, (png_const_structrp png_ptr,
2283
    png_inforp info_ptr, png_charpp name, int *compression_type,
2284
    png_bytepp profile, png_uint_32 *proflen));
2285 2286
#endif

2287
#ifdef PNG_iCCP_SUPPORTED
2288 2289 2290
PNG_EXPORT(159, void, png_set_iCCP, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_charp name, int compression_type,
    png_const_bytep profile, png_uint_32 proflen));
2291 2292
#endif

2293
#ifdef PNG_sPLT_SUPPORTED
2294 2295
PNG_EXPORT(160, int, png_get_sPLT, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_sPLT_tpp entries));
2296 2297
#endif

2298
#ifdef PNG_sPLT_SUPPORTED
2299 2300
PNG_EXPORT(161, void, png_set_sPLT, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_sPLT_tp entries, int nentries));
2301 2302
#endif

2303
#ifdef PNG_TEXT_SUPPORTED
2304
/* png_get_text also returns the number of text chunks in *num_text */
2305 2306
PNG_EXPORT(162, int, png_get_text, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_textp *text_ptr, int *num_text));
2307
#endif
A
Andreas Dilger 已提交
2308

2309
/* Note while png_set_text() will accept a structure whose text,
2310 2311 2312 2313
 * language, and  translated keywords are NULL pointers, the structure
 * returned by png_get_text will always contain regular
 * zero-terminated C strings.  They might be empty strings but
 * they will never be NULL pointers.
2314 2315
 */

2316
#ifdef PNG_TEXT_SUPPORTED
2317 2318
PNG_EXPORT(163, void, png_set_text, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_textp text_ptr, int num_text));
2319
#endif
A
Andreas Dilger 已提交
2320

2321
#ifdef PNG_tIME_SUPPORTED
2322 2323
PNG_EXPORT(164, png_uint_32, png_get_tIME, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_timep *mod_time));
2324
#endif
A
Andreas Dilger 已提交
2325

2326
#ifdef PNG_tIME_SUPPORTED
2327 2328
PNG_EXPORT(165, void, png_set_tIME, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_const_timep mod_time));
2329
#endif
A
Andreas Dilger 已提交
2330

2331
#ifdef PNG_tRNS_SUPPORTED
2332 2333
PNG_EXPORT(166, png_uint_32, png_get_tRNS, (png_const_structrp png_ptr,
    png_inforp info_ptr, png_bytep *trans_alpha, int *num_trans,
2334
    png_color_16p *trans_color));
2335 2336
#endif

2337
#ifdef PNG_tRNS_SUPPORTED
2338 2339
PNG_EXPORT(167, void, png_set_tRNS, (png_structrp png_ptr,
    png_inforp info_ptr, png_const_bytep trans_alpha, int num_trans,
2340
    png_const_color_16p trans_color));
2341 2342
#endif

2343
#ifdef PNG_sCAL_SUPPORTED
2344
PNG_FP_EXPORT(168, png_uint_32, png_get_sCAL, (png_const_structrp png_ptr,
2345 2346 2347
    png_const_inforp info_ptr, int *unit, double *width, double *height))
#if defined(PNG_FLOATING_ARITHMETIC_SUPPORTED) || \
   defined(PNG_FLOATING_POINT_SUPPORTED)
2348
/* NOTE: this API is currently implemented using floating point arithmetic,
2349 2350 2351 2352
 * consequently it can only be used on systems with floating point support.
 * In any case the range of values supported by png_fixed_point is small and it
 * is highly recommended that png_get_sCAL_s be used instead.
 */
2353
PNG_FIXED_EXPORT(214, png_uint_32, png_get_sCAL_fixed,
2354
    (png_const_structrp png_ptr, png_const_inforp info_ptr, int *unit,
2355
    png_fixed_point *width, png_fixed_point *height))
2356 2357
#endif
PNG_EXPORT(169, png_uint_32, png_get_sCAL_s,
2358
    (png_const_structrp png_ptr, png_const_inforp info_ptr, int *unit,
2359
    png_charpp swidth, png_charpp sheight));
2360

2361
PNG_FP_EXPORT(170, void, png_set_sCAL, (png_const_structrp png_ptr,
2362
    png_inforp info_ptr, int unit, double width, double height))
2363
PNG_FIXED_EXPORT(213, void, png_set_sCAL_fixed, (png_const_structrp png_ptr,
2364
   png_inforp info_ptr, int unit, png_fixed_point width,
2365
   png_fixed_point height))
2366 2367 2368
PNG_EXPORT(171, void, png_set_sCAL_s, (png_const_structrp png_ptr,
    png_inforp info_ptr, int unit,
    png_const_charp swidth, png_const_charp sheight));
2369
#endif /* PNG_sCAL_SUPPORTED */
2370

2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402
#ifdef PNG_SET_UNKNOWN_CHUNKS_SUPPORTED
/* Provide the default handling for all unknown chunks or, optionally, for
 * specific unknown chunks.
 *
 * NOTE: prior to 1.6.0 the handling specified for particular chunks on read was
 * ignored and the default was used, the per-chunk setting only had an effect on
 * write.  If you wish to have chunk-specific handling on read in code that must
 * work on earlier versions you must use a user chunk callback to specify the
 * desired handling (keep or discard.)
 *
 * The 'keep' parameter is a PNG_HANDLE_CHUNK_ value as listed below.  The
 * parameter is interpreted as follows:
 *
 * READ:
 *    PNG_HANDLE_CHUNK_AS_DEFAULT:
 *       Known chunks: do normal libpng processing, do not keep the chunk (but
 *          see the comments below about PNG_HANDLE_AS_UNKNOWN_SUPPORTED)
 *       Unknown chunks: for a specific chunk use the global default, when used
 *          as the default discard the chunk data.
 *    PNG_HANDLE_CHUNK_NEVER:
 *       Discard the chunk data.
 *    PNG_HANDLE_CHUNK_IF_SAFE:
 *       Keep the chunk data if the chunk is not critical else raise a chunk
 *       error.
 *    PNG_HANDLE_CHUNK_ALWAYS:
 *       Keep the chunk data.
 *
 * If the chunk data is saved it can be retrieved using png_get_unknown_chunks,
 * below.  Notice that specifying "AS_DEFAULT" as a global default is equivalent
 * to specifying "NEVER", however when "AS_DEFAULT" is used for specific chunks
 * it simply resets the behavior to the libpng default.
 *
2403
 * INTERACTION WTIH USER CHUNK CALLBACKS:
2404 2405 2406 2407 2408 2409
 * The per-chunk handling is always used when there is a png_user_chunk_ptr
 * callback and the callback returns 0; the chunk is then always stored *unless*
 * it is critical and the per-chunk setting is other than ALWAYS.  Notice that
 * the global default is *not* used in this case.  (In effect the per-chunk
 * value is incremented to at least IF_SAFE.)
 *
2410 2411 2412 2413 2414 2415 2416 2417
 * IMPORTANT NOTE: this behavior will change in libpng 1.7 - the global and
 * per-chunk defaults will be honored.  If you want to preserve the current
 * behavior when your callback returns 0 you must set PNG_HANDLE_CHUNK_IF_SAFE
 * as the default - if you don't do this libpng 1.6 will issue a warning.
 *
 * If you want unhandled unknown chunks to be discarded in libpng 1.6 and
 * earlier simply return '1' (handled).
 *
2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469
 * PNG_HANDLE_AS_UNKNOWN_SUPPORTED:
 *    If this is *not* set known chunks will always be handled by libpng and
 *    will never be stored in the unknown chunk list.  Known chunks listed to
 *    png_set_keep_unknown_chunks will have no effect.  If it is set then known
 *    chunks listed with a keep other than AS_DEFAULT will *never* be processed
 *    by libpng, in addition critical chunks must either be processed by the
 *    callback or saved.
 *
 *    The IHDR and IEND chunks must not be listed.  Because this turns off the
 *    default handling for chunks that would otherwise be recognized the
 *    behavior of libpng transformations may well become incorrect!
 *
 * WRITE:
 *    When writing chunks the options only apply to the chunks specified by
 *    png_set_unknown_chunks (below), libpng will *always* write known chunks
 *    required by png_set_ calls and will always write the core critical chunks
 *    (as required for PLTE).
 *
 *    Each chunk in the png_set_unknown_chunks list is looked up in the
 *    png_set_keep_unknown_chunks list to find the keep setting, this is then
 *    interpreted as follows:
 *
 *    PNG_HANDLE_CHUNK_AS_DEFAULT:
 *       Write safe-to-copy chunks and write other chunks if the global
 *       default is set to _ALWAYS, otherwise don't write this chunk.
 *    PNG_HANDLE_CHUNK_NEVER:
 *       Do not write the chunk.
 *    PNG_HANDLE_CHUNK_IF_SAFE:
 *       Write the chunk if it is safe-to-copy, otherwise do not write it.
 *    PNG_HANDLE_CHUNK_ALWAYS:
 *       Write the chunk.
 *
 * Note that the default behavior is effectively the opposite of the read case -
 * in read unknown chunks are not stored by default, in write they are written
 * by default.  Also the behavior of PNG_HANDLE_CHUNK_IF_SAFE is very different
 * - on write the safe-to-copy bit is checked, on read the critical bit is
 * checked and on read if the chunk is critical an error will be raised.
 *
 * num_chunks:
 * ===========
 *    If num_chunks is positive, then the "keep" parameter specifies the manner
 *    for handling only those chunks appearing in the chunk_list array,
 *    otherwise the chunk list array is ignored.
 *
 *    If num_chunks is 0 the "keep" parameter specifies the default behavior for
 *    unknown chunks, as described above.
 *
 *    If num_chunks is negative, then the "keep" parameter specifies the manner
 *    for handling all unknown chunks plus all chunks recognized by libpng
 *    except for the IHDR, PLTE, tRNS, IDAT, and IEND chunks (which continue to
 *    be processed by libpng.
 */
2470
PNG_EXPORT(172, void, png_set_keep_unknown_chunks, (png_structrp png_ptr,
2471
    int keep, png_const_bytep chunk_list, int num_chunks));
2472

2473 2474 2475
/* The "keep" PNG_HANDLE_CHUNK_ parameter for the specified chunk is returned;
 * the result is therefore true (non-zero) if special handling is required,
 * false for the default handling.
2476
 */
2477
PNG_EXPORT(173, int, png_handle_as_unknown, (png_const_structrp png_ptr,
2478
    png_const_bytep chunk_name));
2479
#endif
2480 2481

#ifdef PNG_STORE_UNKNOWN_CHUNKS_SUPPORTED
2482
PNG_EXPORT(174, void, png_set_unknown_chunks, (png_const_structrp png_ptr,
2483
    png_inforp info_ptr, png_const_unknown_chunkp unknowns,
2484
    int num_unknowns));
2485 2486 2487 2488 2489 2490 2491 2492 2493
   /* NOTE: prior to 1.6.0 this routine set the 'location' field of the added
    * unknowns to the location currently stored in the png_struct.  This is
    * invariably the wrong value on write.  To fix this call the following API
    * for each chunk in the list with the correct location.  If you know your
    * code won't be compiled on earlier versions you can rely on
    * png_set_unknown_chunks(write-ptr, png_get_unknown_chunks(read-ptr)) doing
    * the correct thing.
    */

2494 2495
PNG_EXPORT(175, void, png_set_unknown_chunk_location,
    (png_const_structrp png_ptr, png_inforp info_ptr, int chunk, int location));
2496

2497
PNG_EXPORT(176, int, png_get_unknown_chunks, (png_const_structrp png_ptr,
2498
    png_inforp info_ptr, png_unknown_chunkpp entries));
2499 2500
#endif

2501
/* Png_free_data() will turn off the "valid" flag for anything it frees.
2502
 * If you need to turn it off for a chunk that your application has freed,
2503 2504
 * you can use png_set_invalid(png_ptr, info_ptr, PNG_INFO_CHNK);
 */
2505 2506
PNG_EXPORT(177, void, png_set_invalid, (png_const_structrp png_ptr,
    png_inforp info_ptr, int mask));
2507

2508
#ifdef PNG_INFO_IMAGE_SUPPORTED
2509
/* The "params" pointer is currently not used and is for future expansion. */
2510
PNG_EXPORT(178, void, png_read_png, (png_structrp png_ptr, png_inforp info_ptr,
2511
    int transforms, png_voidp params));
2512
PNG_EXPORT(179, void, png_write_png, (png_structrp png_ptr, png_inforp info_ptr,
2513
    int transforms, png_voidp params));
2514 2515
#endif

2516
PNG_EXPORT(180, png_const_charp, png_get_copyright,
2517
    (png_const_structrp png_ptr));
2518
PNG_EXPORT(181, png_const_charp, png_get_header_ver,
2519
    (png_const_structrp png_ptr));
2520
PNG_EXPORT(182, png_const_charp, png_get_header_version,
2521
    (png_const_structrp png_ptr));
2522
PNG_EXPORT(183, png_const_charp, png_get_libpng_ver,
2523
    (png_const_structrp png_ptr));
2524

2525
#ifdef PNG_MNG_FEATURES_SUPPORTED
2526
PNG_EXPORT(184, png_uint_32, png_permit_mng_features, (png_structrp png_ptr,
2527
    png_uint_32 mng_features_permitted));
2528 2529
#endif

2530 2531 2532 2533 2534
/* For use in png_set_keep_unknown, added to version 1.2.6 */
#define PNG_HANDLE_CHUNK_AS_DEFAULT   0
#define PNG_HANDLE_CHUNK_NEVER        1
#define PNG_HANDLE_CHUNK_IF_SAFE      2
#define PNG_HANDLE_CHUNK_ALWAYS       3
2535
#define PNG_HANDLE_CHUNK_LAST         4
2536

2537
/* Strip the prepended error numbers ("#nnn ") from error and warning
2538 2539
 * messages before passing them to the error or warning handler.
 */
2540
#ifdef PNG_ERROR_NUMBERS_SUPPORTED
2541
PNG_EXPORT(185, void, png_set_strip_error_numbers, (png_structrp png_ptr,
2542
    png_uint_32 strip_mode));
2543
#endif
2544

2545
/* Added in libpng-1.2.6 */
2546
#ifdef PNG_SET_USER_LIMITS_SUPPORTED
2547
PNG_EXPORT(186, void, png_set_user_limits, (png_structrp png_ptr,
2548
    png_uint_32 user_width_max, png_uint_32 user_height_max));
2549
PNG_EXPORT(187, png_uint_32, png_get_user_width_max,
2550
    (png_const_structrp png_ptr));
2551
PNG_EXPORT(188, png_uint_32, png_get_user_height_max,
2552
    (png_const_structrp png_ptr));
2553
/* Added in libpng-1.4.0 */
2554
PNG_EXPORT(189, void, png_set_chunk_cache_max, (png_structrp png_ptr,
2555
    png_uint_32 user_chunk_cache_max));
2556
PNG_EXPORT(190, png_uint_32, png_get_chunk_cache_max,
2557
    (png_const_structrp png_ptr));
2558
/* Added in libpng-1.4.1 */
2559
PNG_EXPORT(191, void, png_set_chunk_malloc_max, (png_structrp png_ptr,
2560 2561
    png_alloc_size_t user_chunk_cache_max));
PNG_EXPORT(192, png_alloc_size_t, png_get_chunk_malloc_max,
2562
    (png_const_structrp png_ptr));
2563 2564
#endif

G
[devel]  
Glenn Randers-Pehrson 已提交
2565
#if defined(PNG_INCH_CONVERSIONS_SUPPORTED)
2566
PNG_EXPORT(193, png_uint_32, png_get_pixels_per_inch,
2567
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2568

2569
PNG_EXPORT(194, png_uint_32, png_get_x_pixels_per_inch,
2570
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2571

2572
PNG_EXPORT(195, png_uint_32, png_get_y_pixels_per_inch,
2573
    (png_const_structrp png_ptr, png_const_inforp info_ptr));
2574

2575
PNG_FP_EXPORT(196, float, png_get_x_offset_inches,
2576
    (png_const_structrp png_ptr, png_const_inforp info_ptr))
G
[devel]  
Glenn Randers-Pehrson 已提交
2577
#ifdef PNG_FIXED_POINT_SUPPORTED /* otherwise not implemented. */
2578
PNG_FIXED_EXPORT(211, png_fixed_point, png_get_x_offset_inches_fixed,
2579
    (png_const_structrp png_ptr, png_const_inforp info_ptr))
G
[devel]  
Glenn Randers-Pehrson 已提交
2580
#endif
2581

2582
PNG_FP_EXPORT(197, float, png_get_y_offset_inches, (png_const_structrp png_ptr,
2583
    png_const_inforp info_ptr))
G
[devel]  
Glenn Randers-Pehrson 已提交
2584
#ifdef PNG_FIXED_POINT_SUPPORTED /* otherwise not implemented. */
2585
PNG_FIXED_EXPORT(212, png_fixed_point, png_get_y_offset_inches_fixed,
2586
    (png_const_structrp png_ptr, png_const_inforp info_ptr))
G
[devel]  
Glenn Randers-Pehrson 已提交
2587
#endif
2588

2589
#  ifdef PNG_pHYs_SUPPORTED
2590 2591
PNG_EXPORT(198, png_uint_32, png_get_pHYs_dpi, (png_const_structrp png_ptr,
    png_const_inforp info_ptr, png_uint_32 *res_x, png_uint_32 *res_y,
2592
    int *unit_type));
2593
#  endif /* PNG_pHYs_SUPPORTED */
G
[devel]  
Glenn Randers-Pehrson 已提交
2594
#endif  /* PNG_INCH_CONVERSIONS_SUPPORTED */
2595

2596 2597
/* Added in libpng-1.4.0 */
#ifdef PNG_IO_STATE_SUPPORTED
2598
PNG_EXPORT(199, png_uint_32, png_get_io_state, (png_const_structrp png_ptr));
2599 2600

/* Removed from libpng 1.6; use png_get_io_chunk_type. */
2601
PNG_REMOVED(200, png_const_bytep, png_get_io_chunk_name, (png_structrp png_ptr),
2602
    PNG_DEPRECATED)
2603

2604
PNG_EXPORT(216, png_uint_32, png_get_io_chunk_type,
2605
    (png_const_structrp png_ptr));
2606 2607

/* The flags returned by png_get_io_state() are the following: */
2608 2609 2610 2611 2612 2613 2614 2615 2616
#  define PNG_IO_NONE        0x0000   /* no I/O at this moment */
#  define PNG_IO_READING     0x0001   /* currently reading */
#  define PNG_IO_WRITING     0x0002   /* currently writing */
#  define PNG_IO_SIGNATURE   0x0010   /* currently at the file signature */
#  define PNG_IO_CHUNK_HDR   0x0020   /* currently at the chunk header */
#  define PNG_IO_CHUNK_DATA  0x0040   /* currently at the chunk data */
#  define PNG_IO_CHUNK_CRC   0x0080   /* currently at the chunk crc */
#  define PNG_IO_MASK_OP     0x000f   /* current operation: reading/writing */
#  define PNG_IO_MASK_LOC    0x00f0   /* current location: sig/hdr/data/crc */
2617 2618
#endif /* ?PNG_IO_STATE_SUPPORTED */

2619 2620 2621 2622 2623 2624 2625 2626 2627 2628
/* Interlace support.  The following macros are always defined so that if
 * libpng interlace handling is turned off the macros may be used to handle
 * interlaced images within the application.
 */
#define PNG_INTERLACE_ADAM7_PASSES 7

/* Two macros to return the first row and first column of the original,
 * full, image which appears in a given pass.  'pass' is in the range 0
 * to 6 and the result is in the range 0 to 7.
 */
2629 2630 2631 2632 2633 2634 2635 2636 2637 2638
#define PNG_PASS_START_ROW(pass) (((1&~(pass))<<(3-((pass)>>1)))&7)
#define PNG_PASS_START_COL(pass) (((1& (pass))<<(3-(((pass)+1)>>1)))&7)

/* A macro to return the offset between pixels in the output row for a pair of
 * pixels in the input - effectively the inverse of the 'COL_SHIFT' macro that
 * follows.  Note that ROW_OFFSET is the offset from one row to the next whereas
 * COL_OFFSET is from one column to the next, within a row.
 */
#define PNG_PASS_ROW_OFFSET(pass) ((pass)>2?(8>>(((pass)-1)>>1)):8)
#define PNG_PASS_COL_OFFSET(pass) (1<<((7-(pass))>>1))
2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656

/* Two macros to help evaluate the number of rows or columns in each
 * pass.  This is expressed as a shift - effectively log2 of the number or
 * rows or columns in each 8x8 tile of the original image.
 */
#define PNG_PASS_ROW_SHIFT(pass) ((pass)>2?(8-(pass))>>1:3)
#define PNG_PASS_COL_SHIFT(pass) ((pass)>1?(7-(pass))>>1:3)

/* Hence two macros to determine the number of rows or columns in a given
 * pass of an image given its height or width.  In fact these macros may
 * return non-zero even though the sub-image is empty, because the other
 * dimension may be empty for a small image.
 */
#define PNG_PASS_ROWS(height, pass) (((height)+(((1<<PNG_PASS_ROW_SHIFT(pass))\
   -1)-PNG_PASS_START_ROW(pass)))>>PNG_PASS_ROW_SHIFT(pass))
#define PNG_PASS_COLS(width, pass) (((width)+(((1<<PNG_PASS_COL_SHIFT(pass))\
   -1)-PNG_PASS_START_COL(pass)))>>PNG_PASS_COL_SHIFT(pass))

2657 2658 2659
/* For the reader row callbacks (both progressive and sequential) it is
 * necessary to find the row in the output image given a row in an interlaced
 * image, so two more macros:
2660
 */
2661 2662 2663 2664
#define PNG_ROW_FROM_PASS_ROW(y_in, pass) \
   (((y_in)<<PNG_PASS_ROW_SHIFT(pass))+PNG_PASS_START_ROW(pass))
#define PNG_COL_FROM_PASS_COL(x_in, pass) \
   (((x_in)<<PNG_PASS_COL_SHIFT(pass))+PNG_PASS_START_COL(pass))
2665 2666 2667 2668 2669 2670 2671 2672

/* Two macros which return a boolean (0 or 1) saying whether the given row
 * or column is in a particular pass.  These use a common utility macro that
 * returns a mask for a given pass - the offset 'off' selects the row or
 * column version.  The mask has the appropriate bit set for each column in
 * the tile.
 */
#define PNG_PASS_MASK(pass,off) ( \
2673 2674
   ((0x110145AF>>(((7-(off))-(pass))<<2)) & 0xF) | \
   ((0x01145AF0>>(((7-(off))-(pass))<<2)) & 0xF0))
2675 2676 2677 2678 2679 2680

#define PNG_ROW_IN_INTERLACE_PASS(y, pass) \
   ((PNG_PASS_MASK(pass,0) >> ((y)&7)) & 1)
#define PNG_COL_IN_INTERLACE_PASS(x, pass) \
   ((PNG_PASS_MASK(pass,1) >> ((x)&7)) & 1)

2681
#ifdef PNG_READ_COMPOSITE_NODIV_SUPPORTED
2682 2683 2684
/* With these routines we avoid an integer divide, which will be slower on
 * most machines.  However, it does take more operations than the corresponding
 * divide method, so it may be slower on a few RISC systems.  There are two
2685 2686 2687 2688 2689 2690 2691 2692 2693
 * shifts (by 8 or 16 bits) and an addition, versus a single integer divide.
 *
 * Note that the rounding factors are NOT supposed to be the same!  128 and
 * 32768 are correct for the NODIV code; 127 and 32767 are correct for the
 * standard method.
 *
 * [Optimized code by Greg Roelofs and Mark Adler...blame us for bugs. :-) ]
 */

2694
 /* fg and bg should be in `gamma 1.0' space; alpha is the opacity */
2695

2696 2697 2698 2699
#  define png_composite(composite, fg, alpha, bg)         \
     { png_uint_16 temp = (png_uint_16)((png_uint_16)(fg) \
           * (png_uint_16)(alpha)                         \
           + (png_uint_16)(bg)*(png_uint_16)(255          \
2700
           - (png_uint_16)(alpha)) + 128);                \
2701
       (composite) = (png_byte)((temp + (temp >> 8)) >> 8); }
2702

2703 2704 2705
#  define png_composite_16(composite, fg, alpha, bg)       \
     { png_uint_32 temp = (png_uint_32)((png_uint_32)(fg)  \
           * (png_uint_32)(alpha)                          \
2706 2707
           + (png_uint_32)(bg)*(65535                      \
           - (png_uint_32)(alpha)) + 32768);               \
2708 2709
       (composite) = (png_uint_16)((temp + (temp >> 16)) >> 16); }

2710
#else  /* Standard method using integer division */
2711

2712 2713
#  define png_composite(composite, fg, alpha, bg)                          \
     (composite) = (png_byte)(((png_uint_16)(fg) * (png_uint_16)(alpha) +  \
2714
     (png_uint_16)(bg) * (png_uint_16)(255 - (png_uint_16)(alpha)) +       \
2715
     127) / 255)
2716 2717

#  define png_composite_16(composite, fg, alpha, bg)                         \
2718
     (composite) = (png_uint_16)(((png_uint_32)(fg) * (png_uint_32)(alpha) + \
2719 2720
     (png_uint_32)(bg)*(png_uint_32)(65535 - (png_uint_32)(alpha)) +         \
     32767) / 65535)
2721 2722
#endif /* PNG_READ_COMPOSITE_NODIV_SUPPORTED */

2723
#ifdef PNG_READ_INT_FUNCTIONS_SUPPORTED
2724 2725 2726
PNG_EXPORT(201, png_uint_32, png_get_uint_32, (png_const_bytep buf));
PNG_EXPORT(202, png_uint_16, png_get_uint_16, (png_const_bytep buf));
PNG_EXPORT(203, png_int_32, png_get_int_32, (png_const_bytep buf));
2727 2728
#endif

2729
PNG_EXPORT(204, png_uint_32, png_get_uint_31, (png_const_structrp png_ptr,
2730
    png_const_bytep buf));
2731 2732
/* No png_get_int_16 -- may be added if there's a real need for it. */

2733
/* Place a 32-bit number into a buffer in PNG byte order (big-endian). */
2734
#ifdef PNG_WRITE_INT_FUNCTIONS_SUPPORTED
2735
PNG_EXPORT(205, void, png_save_uint_32, (png_bytep buf, png_uint_32 i));
2736
#endif
2737
#ifdef PNG_SAVE_INT_32_SUPPORTED
2738
PNG_EXPORT(206, void, png_save_int_32, (png_bytep buf, png_int_32 i));
2739
#endif
2740 2741

/* Place a 16-bit number into a buffer in PNG byte order.
2742
 * The parameter is declared unsigned int, not png_uint_16,
2743 2744
 * just to avoid potential problems on pre-ANSI C compilers.
 */
2745
#ifdef PNG_WRITE_INT_FUNCTIONS_SUPPORTED
2746
PNG_EXPORT(207, void, png_save_uint_16, (png_bytep buf, unsigned int i));
2747
/* No png_save_int_16 -- may be added if there's a real need for it. */
2748
#endif
2749

2750 2751 2752 2753 2754
#ifdef PNG_USE_READ_MACROS
/* Inline macros to do direct reads of bytes from the input buffer.
 * The png_get_int_32() routine assumes we are using two's complement
 * format for negative values, which is almost certainly true.
 */
2755
#  define PNG_get_uint_32(buf) \
2756 2757 2758 2759 2760 2761 2762 2763
     (((png_uint_32)(*(buf)) << 24) + \
      ((png_uint_32)(*((buf) + 1)) << 16) + \
      ((png_uint_32)(*((buf) + 2)) << 8) + \
      ((png_uint_32)(*((buf) + 3))))

   /* From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
    * function) incorrectly returned a value of type png_uint_32.
    */
2764
#  define PNG_get_uint_16(buf) \
2765 2766 2767 2768
     ((png_uint_16) \
      (((unsigned int)(*(buf)) << 8) + \
       ((unsigned int)(*((buf) + 1)))))

2769
#  define PNG_get_int_32(buf) \
2770 2771 2772
     ((png_int_32)((*(buf) & 0x80) \
      ? -((png_int_32)((png_get_uint_32(buf) ^ 0xffffffffL) + 1)) \
      : (png_int_32)png_get_uint_32(buf)))
2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788

   /* If PNG_PREFIX is defined the same thing as below happens in pnglibconf.h,
    * but defining a macro name prefixed with PNG_PREFIX.
    */
#  ifndef PNG_PREFIX
#     define png_get_uint_32(buf) PNG_get_uint_32(buf)
#     define png_get_uint_16(buf) PNG_get_uint_16(buf)
#     define png_get_int_32(buf)  PNG_get_int_32(buf)
#  endif
#else
#  ifdef PNG_PREFIX
      /* No macros; revert to the (redefined) function */
#     define PNG_get_uint_32 (png_get_uint_32)
#     define PNG_get_uint_16 (png_get_uint_16)
#     define PNG_get_int_32  (png_get_int_32)
#  endif
2789 2790
#endif

2791 2792
/*******************************************************************************
 *  SIMPLIFIED API
2793 2794
 *******************************************************************************
 *
2795 2796
 * Please read the documentation in libpng-manual.txt (TODO: write said
 * documentation) if you don't understand what follows.
2797 2798 2799 2800 2801 2802 2803
 *
 * The simplified API hides the details of both libpng and the PNG file format
 * itself.  It allows PNG files to be read into a very limited number of
 * in-memory bitmap formats or to be written from the same formats.  If these
 * formats do not accomodate your needs then you can, and should, use the more
 * sophisticated APIs above - these support a wide variety of in-memory formats
 * and a wide variety of sophisticated transformations to those formats as well
2804
 * as a wide variety of APIs to manipulate ancillary information.
2805 2806 2807
 *
 * To read a PNG file using the simplified API:
 *
2808 2809
 * 1) Declare a 'png_image' structure (see below) on the stack and set the
 *    version field to PNG_IMAGE_VERSION.
2810
 * 2) Call the appropriate png_image_begin_read... function.
2811 2812 2813 2814
 * 3) Set the png_image 'format' member to the required sample format.
 * 4) Allocate a buffer for the image and, if required, the color-map.
 * 5) Call png_image_finish_read to read the image and, if required, the
 *    color-map into your buffers.
2815
 *
2816 2817 2818
 * There are no restrictions on the format of the PNG input itself; all valid
 * color types, bit depths, and interlace methods are acceptable, and the
 * input image is transformed as necessary to the requested in-memory format
2819 2820 2821 2822
 * during the png_image_finish_read() step.  The only caveat is that if you
 * request a color-mapped image from a PNG that is full-color or makes
 * complex use of an alpha channel the transformation is extremely lossy and the
 * result may look terrible.
2823
 *
2824 2825 2826 2827
 * To write a PNG file using the simplified API:
 *
 * 1) Declare a 'png_image' structure on the stack and memset() it to all zero.
 * 2) Initialize the members of the structure that describe the image, setting
2828
 *    the 'format' member to the format of the image samples.
2829
 * 3) Call the appropriate png_image_write... function with a pointer to the
2830
 *    image and, if necessary, the color-map to write the PNG data.
2831
 *
2832
 * png_image is a structure that describes the in-memory format of an image
2833
 * when it is being read or defines the in-memory format of an image that you
2834 2835
 * need to write:
 */
2836
#define PNG_IMAGE_VERSION 1
2837

2838 2839 2840
typedef struct png_control *png_controlp;
typedef struct
{
2841 2842 2843 2844 2845 2846 2847 2848
   png_controlp opaque;    /* Initialize to NULL, free with png_image_free */
   png_uint_32  version;   /* Set to PNG_IMAGE_VERSION */
   png_uint_32  width;     /* Image width in pixels (columns) */
   png_uint_32  height;    /* Image height in pixels (rows) */
   png_uint_32  format;    /* Image format as defined below */
   png_uint_32  flags;     /* A bit mask containing informational flags */
   png_uint_32  colormap_entries;
                           /* Number of entries in the color-map */
2849

2850 2851
   /* In the event of an error or warning the following field will be set to a
    * non-zero value and the 'message' field will contain a '\0' terminated
2852 2853 2854 2855
    * string with the libpng error or warning message.  If both warnings and
    * an error were encountered, only the error is recorded.  If there
    * are multiple warnings, only the first one is recorded.
    *
2856 2857 2858 2859 2860 2861 2862 2863 2864
    * The upper 30 bits of this value are reserved, the low two bits contain
    * a value as follows:
    */
#  define PNG_IMAGE_WARNING 1
#  define PNG_IMAGE_ERROR 2
   /*
    * The result is a two bit code such that a value more than 1 indicates
    * a failure in the API just called:
    *
2865
    *    0 - no warning or error
2866 2867 2868
    *    1 - warning
    *    2 - error
    *    3 - error preceded by warning
2869
    */
2870 2871
#  define PNG_IMAGE_FAILED(png_cntrl) ((((png_cntrl).warning_or_error)&0x03)>1)

2872
   png_uint_32  warning_or_error;
2873

2874 2875 2876
   char         message[64];
} png_image, *png_imagep;

2877 2878
/* The samples of the image have one to four channels whose components have
 * original values in the range 0 to 1.0:
2879 2880 2881 2882 2883 2884
 *
 * 1: A single gray or luminance channel (G).
 * 2: A gray/luminance channel and an alpha channel (GA).
 * 3: Three red, green, blue color channels (RGB).
 * 4: Three color channels and an alpha channel (RGBA).
 *
2885
 * The components are encoded in one of two ways:
2886
 *
2887
 * a) As a small integer, value 0..255, contained in a single byte.  For the
2888
 * alpha channel the original value is simply value/255.  For the color or
2889 2890 2891
 * luminance channels the value is encoded according to the sRGB specification
 * and matches the 8-bit format expected by typical display devices.
 *
2892
 * The color/gray channels are not scaled (pre-multiplied) by the alpha
2893 2894
 * channel and are suitable for passing to color management software.
 *
2895
 * b) As a value in the range 0..65535, contained in a 2-byte integer.  All
2896 2897 2898 2899 2900
 * channels can be converted to the original value by dividing by 65535; all
 * channels are linear.  Color channels use the RGB encoding (RGB end-points) of
 * the sRGB specification.  This encoding is identified by the
 * PNG_FORMAT_FLAG_LINEAR flag below.
 *
2901 2902 2903 2904 2905 2906
 * When the simplified API needs to convert between sRGB and linear colorspaces,
 * the actual sRGB transfer curve defined in the sRGB specification (see the
 * article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
 * approximation used elsewhere in libpng.
 *
 * When an alpha channel is present it is expected to denote pixel coverage
2907
 * of the color or luminance channels and is returned as an associated alpha
2908 2909
 * channel: the color/gray channels are scaled (pre-multiplied) by the alpha
 * value.
2910 2911 2912 2913 2914 2915
 *
 * The samples are either contained directly in the image data, between 1 and 8
 * bytes per pixel according to the encoding, or are held in a color-map indexed
 * by bytes in the image data.  In the case of a color-map the color-map entries
 * are individual samples, encoded as above, and the image data has one byte per
 * pixel to select the relevant sample from the color-map.
2916 2917 2918 2919 2920
 */

/* PNG_FORMAT_*
 *
 * #defines to be used in png_image::format.  Each #define identifies a
2921 2922
 * particular layout of sample data and, if present, alpha values.  There are
 * separate defines for each of the two component encodings.
2923
 *
2924 2925 2926 2927 2928 2929 2930 2931 2932 2933
 * A format is built up using single bit flag values.  All combinations are
 * valid.  Formats can be built up from the flag values or you can use one of
 * the predefined values below.  When testing formats always use the FORMAT_FLAG
 * macros to test for individual features - future versions of the library may
 * add new flags.
 *
 * When reading or writing color-mapped images the format should be set to the
 * format of the entries in the color-map then png_image_{read,write}_colormap
 * called to read or write the color-map and set the format correctly for the
 * image data.  Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
2934
 *
2935 2936 2937 2938
 * NOTE: libpng can be built with particular features disabled, if you see
 * compiler errors because the definition of one of the following flags has been
 * compiled out it is because libpng does not have the required support.  It is
 * possible, however, for the libpng configuration to enable the format on just
2939
 * read or just write; in that case you may see an error at run time.  You can
2940 2941
 * guard against this by checking for the definition of the appropriate
 * "_SUPPORTED" macro, one of:
2942 2943 2944
 *
 *    PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
 */
2945 2946 2947 2948
#define PNG_FORMAT_FLAG_ALPHA    0x01U /* format with an alpha channel */
#define PNG_FORMAT_FLAG_COLOR    0x02U /* color format: otherwise grayscale */
#define PNG_FORMAT_FLAG_LINEAR   0x04U /* 2 byte channels else 1 byte */
#define PNG_FORMAT_FLAG_COLORMAP 0x08U /* image data is color-mapped */
2949 2950

#ifdef PNG_FORMAT_BGR_SUPPORTED
2951
#  define PNG_FORMAT_FLAG_BGR    0x10U /* BGR colors, else order is RGB */
2952 2953 2954
#endif

#ifdef PNG_FORMAT_AFIRST_SUPPORTED
2955
#  define PNG_FORMAT_FLAG_AFIRST 0x20U /* alpha channel comes first */
2956 2957
#endif

2958
/* Commonly used formats have predefined macros.
2959
 *
2960
 * First the single byte (sRGB) formats:
2961 2962 2963
 */
#define PNG_FORMAT_GRAY 0
#define PNG_FORMAT_GA   PNG_FORMAT_FLAG_ALPHA
2964
#define PNG_FORMAT_AG   (PNG_FORMAT_GA|PNG_FORMAT_FLAG_AFIRST)
2965 2966 2967 2968 2969 2970 2971
#define PNG_FORMAT_RGB  PNG_FORMAT_FLAG_COLOR
#define PNG_FORMAT_BGR  (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR)
#define PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA)
#define PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST)
#define PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA)
#define PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST)

2972 2973
/* Then the linear 2-byte formats.  When naming these "Y" is used to
 * indicate a luminance (gray) channel.
2974
 */
2975 2976 2977 2978 2979
#define PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR
#define PNG_FORMAT_LINEAR_Y_ALPHA (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA)
#define PNG_FORMAT_LINEAR_RGB (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR)
#define PNG_FORMAT_LINEAR_RGB_ALPHA \
   (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_ALPHA)
2980

2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992
/* With color-mapped formats the image data is one byte for each pixel, the byte
 * is an index into the color-map which is formatted as above.  To obtain a
 * color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP
 * to one of the above definitions, or you can use one of the definitions below.
 */
#define PNG_FORMAT_RGB_COLORMAP  (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_BGR_COLORMAP  (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_RGBA_COLORMAP (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_ARGB_COLORMAP (PNG_FORMAT_ARGB|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_BGRA_COLORMAP (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_COLORMAP)
#define PNG_FORMAT_ABGR_COLORMAP (PNG_FORMAT_ABGR|PNG_FORMAT_FLAG_COLORMAP)

2993 2994
/* PNG_IMAGE macros
 *
2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009
 * These are convenience macros to derive information from a png_image
 * structure.  The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
 * actual image sample values - either the entries in the color-map or the
 * pixels in the image.  The PNG_IMAGE_PIXEL_ macros return corresponding values
 * for the pixels and will always return 1 for color-mapped formats.  The
 * remaining macros return information about the rows in the image and the
 * complete image.
 *
 * NOTE: All the macros that take a png_image::format parameter are compile time
 * constants if the format parameter is, itself, a constant.  Therefore these
 * macros can be used in array declarations and case labels where required.
 * Similarly the macros are also pre-processor constants (sizeof is not used) so
 * they can be used in #if tests.
 *
 * First the information about the samples.
3010
 */
3011 3012
#define PNG_IMAGE_SAMPLE_CHANNELS(fmt)\
   (((fmt)&(PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_ALPHA))+1)
3013 3014
   /* Return the total number of channels in a given format: 1..4 */

3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026
#define PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)\
   ((((fmt) & PNG_FORMAT_FLAG_LINEAR) >> 2)+1)
   /* Return the size in bytes of a single component of a pixel or color-map
    * entry (as appropriate) in the image: 1 or 2.
    */

#define PNG_IMAGE_SAMPLE_SIZE(fmt)\
   (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt))
   /* This is the size of the sample data for one sample.  If the image is
    * color-mapped it is the size of one color-map entry (and image pixels are
    * one byte in size), otherwise it is the size of one image pixel.
    */
3027

3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062
#define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\
   (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256)
   /* The maximum size of the color-map required by the format expressed in a
    * count of components.  This can be used to compile-time allocate a
    * color-map:
    *
    * png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
    *
    * png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
    *
    * Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
    * information from one of the png_image_begin_read_ APIs and dynamically
    * allocate the required memory.
    */

/* Corresponding information about the pixels */
#define PNG_IMAGE_PIXEL_(test,fmt)\
   (((fmt)&PNG_FORMAT_FLAG_COLORMAP)?1:test(fmt))

#define PNG_IMAGE_PIXEL_CHANNELS(fmt)\
   PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_CHANNELS,fmt)
   /* The number of separate channels (components) in a pixel; 1 for a
    * color-mapped image.
    */

#define PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
   PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_COMPONENT_SIZE,fmt)
   /* The size, in bytes, of each component in a pixel; 1 for a color-mapped
    * image.
    */

#define PNG_IMAGE_PIXEL_SIZE(fmt) PNG_IMAGE_PIXEL_(PNG_IMAGE_SAMPLE_SIZE,fmt)
   /* The size, in bytes, of a complete pixel; 1 for a color-mapped image. */

/* Information about the whole row, or whole image */
3063
#define PNG_IMAGE_ROW_STRIDE(image)\
3064
   (PNG_IMAGE_PIXEL_CHANNELS((image).format) * (image).width)
3065 3066
   /* Return the total number of components in a single row of the image; this
    * is the minimum 'row stride', the minimum count of components between each
3067
    * row.  For a color-mapped image this is the minimum number of bytes in a
3068 3069
    * row.
    */
3070 3071

#define PNG_IMAGE_BUFFER_SIZE(image, row_stride)\
3072
   (PNG_IMAGE_PIXEL_COMPONENT_SIZE((image).format)*(image).height*(row_stride))
3073
   /* Return the size, in bytes, of an image buffer given a png_image and a row
3074 3075
    * stride - the number of components to leave space for in each row.
    */
3076

3077 3078 3079 3080 3081 3082
#define PNG_IMAGE_SIZE(image)\
   PNG_IMAGE_BUFFER_SIZE(image, PNG_IMAGE_ROW_STRIDE(image))
   /* Return the size, in bytes, of the image in memory given just a png_image;
    * the row stride is the minimum stride required for the image.
    */

3083 3084 3085 3086 3087 3088 3089 3090
#define PNG_IMAGE_COLORMAP_SIZE(image)\
   (PNG_IMAGE_SAMPLE_SIZE((image).format) * (image).colormap_entries)
   /* Return the size, in bytes, of the color-map of this image.  If the image
    * format is not a color-map format this will return a size sufficient for
    * 256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if
    * you don't want to allocate a color-map in this case.
    */

3091 3092 3093 3094 3095
/* PNG_IMAGE_FLAG_*
 *
 * Flags containing additional information about the image are held in the
 * 'flags' field of png_image.
 */
3096
#define PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB 0x01
3097 3098 3099 3100
   /* This indicates the the RGB values of the in-memory bitmap do not
    * correspond to the red, green and blue end-points defined by sRGB.
    */

3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111
#define PNG_IMAGE_FLAG_FAST 0x02
   /* On write emphasise speed over compression; the resultant PNG file will be
    * larger but will be produced significantly faster, particular for large
    * images.  Do not use this option for images which will be distributed, only
    * used it when producing intermediate files that will be read back in
    * repeatedly.  For a typical 24-bit image the option will double the read
    * speed at the cost of increasing the image size by 25%, however for many
    * more compressible images the PNG file can be 10 times larger with only a
    * slight speed gain.
    */

3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129
#define PNG_IMAGE_FLAG_16BIT_sRGB 0x04
   /* On read if the image is a 16-bit per component image and there is no gAMA
    * or sRGB chunk assume that the components are sRGB encoded.  Notice that
    * images output by the simplified API always have gamma information; setting
    * this flag only affects the interpretation of 16-bit images from an
    * external source.  It is recommended that the application expose this flag
    * to the user; the user can normally easily recognize the difference between
    * linear and sRGB encoding.  This flag has no effect on write - the data
    * passed to the write APIs must have the correct encoding (as defined
    * above.)
    *
    * If the flag is not set (the default) input 16-bit per component data is
    * assumed to be linear.
    *
    * NOTE: the flag can only be set after the png_image_begin_read_ call,
    * because that call initializes the 'flags' field.
    */

3130 3131 3132 3133 3134
#ifdef PNG_SIMPLIFIED_READ_SUPPORTED
/* READ APIs
 * ---------
 *
 * The png_image passed to the read APIs must have been initialized by setting
3135
 * the png_controlp field 'opaque' to NULL (or, safer, memset the whole thing.)
3136 3137 3138 3139
 */
#ifdef PNG_STDIO_SUPPORTED
PNG_EXPORT(234, int, png_image_begin_read_from_file, (png_imagep image,
   const char *file_name));
3140 3141
   /* The named file is opened for read and the image header is filled in
    * from the PNG header in the file.
3142
    */
3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153

PNG_EXPORT(235, int, png_image_begin_read_from_stdio, (png_imagep image,
   FILE* file));
   /* The PNG header is read from the stdio FILE object. */
#endif /* PNG_STDIO_SUPPORTED */

PNG_EXPORT(236, int, png_image_begin_read_from_memory, (png_imagep image,
   png_const_voidp memory, png_size_t size));
   /* The PNG header is read from the given memory buffer. */

PNG_EXPORT(237, int, png_image_finish_read, (png_imagep image,
3154 3155
   png_const_colorp background, void *buffer, png_int_32 row_stride,
   void *colormap));
3156 3157 3158
   /* Finish reading the image into the supplied buffer and clean up the
    * png_image structure.
    *
3159
    * row_stride is the step, in byte or 2-byte units as appropriate,
3160 3161 3162 3163 3164 3165 3166 3167 3168 3169
    * between adjacent rows.  A positive stride indicates that the top-most row
    * is first in the buffer - the normal top-down arrangement.  A negative
    * stride indicates that the bottom-most row is first in the buffer.
    *
    * background need only be supplied if an alpha channel must be removed from
    * a png_byte format and the removal is to be done by compositing on a solid
    * color; otherwise it may be NULL and any composition will be done directly
    * onto the buffer.  The value is an sRGB color to use for the background,
    * for grayscale output the green channel is used.
    *
3170 3171 3172 3173 3174 3175 3176 3177 3178
    * background must be supplied when an alpha channel must be removed from a
    * single byte color-mapped output format, in other words if:
    *
    * 1) The original format from png_image_begin_read_from_* had
    *    PNG_FORMAT_FLAG_ALPHA set.
    * 2) The format set by the application does not.
    * 3) The format set by the application has PNG_FORMAT_FLAG_COLORMAP set and
    *    PNG_FORMAT_FLAG_LINEAR *not* set.
    *
3179
    * For linear output removing the alpha channel is always done by compositing
3180
    * on black and background is ignored.
3181 3182 3183 3184 3185
    *
    * colormap must be supplied when PNG_FORMAT_FLAG_COLORMAP is set.  It must
    * be at least the size (in bytes) returned by PNG_IMAGE_COLORMAP_SIZE.
    * image->colormap_entries will be updated to the actual number of entries
    * written to the colormap; this may be less than the original value.
3186 3187 3188 3189
    */

PNG_EXPORT(238, void, png_image_free, (png_imagep image));
   /* Free any data allocated by libpng in image->opaque, setting the pointer to
3190 3191
    * NULL.  May be called at any time after the structure is initialized.
    */
3192 3193 3194
#endif /* PNG_SIMPLIFIED_READ_SUPPORTED */

#ifdef PNG_SIMPLIFIED_WRITE_SUPPORTED
3195
#ifdef PNG_STDIO_SUPPORTED
3196 3197 3198
/* WRITE APIS
 * ----------
 * For write you must initialize a png_image structure to describe the image to
3199 3200
 * be written.  To do this use memset to set the whole structure to 0 then
 * initialize fields describing your image.
3201
 *
3202
 * version: must be set to PNG_IMAGE_VERSION
3203 3204 3205
 * opaque: must be initialized to NULL
 * width: image width in pixels
 * height: image height in rows
3206
 * format: the format of the data (image and color-map) you wish to write
3207 3208 3209
 * flags: set to 0 unless one of the defined flags applies; set
 *    PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images where the RGB
 *    values do not correspond to the colors in sRGB.
3210
 * colormap_entries: set to the number of entries in the color-map (0 to 256)
3211 3212 3213
 */
PNG_EXPORT(239, int, png_image_write_to_file, (png_imagep image,
   const char *file, int convert_to_8bit, const void *buffer,
3214
   png_int_32 row_stride, const void *colormap));
3215 3216 3217
   /* Write the image to the named file. */

PNG_EXPORT(240, int, png_image_write_to_stdio, (png_imagep image, FILE *file,
3218 3219
   int convert_to_8_bit, const void *buffer, png_int_32 row_stride,
   const void *colormap));
3220 3221
   /* Write the image to the given (FILE*). */

3222 3223 3224 3225 3226 3227 3228 3229 3230
/* With both write APIs if image is in one of the linear formats with 16-bit
 * data then setting convert_to_8_bit will cause the output to be an 8-bit PNG
 * gamma encoded according to the sRGB specification, otherwise a 16-bit linear
 * encoded PNG file is written.
 *
 * With color-mapped data formats the colormap parameter point to a color-map
 * with at least image->colormap_entries encoded in the specified format.  If
 * the format is linear the written PNG color-map will be converted to sRGB
 * regardless of the convert_to_8_bit flag.
3231 3232
 *
 * With all APIs row_stride is handled as in the read APIs - it is the spacing
3233 3234
 * from one row to the next in component sized units (1 or 2 bytes) and if
 * negative indicates a bottom-up row layout in the buffer.
3235
 *
3236
 * Note that the write API does not support interlacing or sub-8-bit pixels.
3237
 */
3238
#endif /* PNG_STDIO_SUPPORTED */
3239 3240 3241 3242 3243
#endif /* PNG_SIMPLIFIED_WRITE_SUPPORTED */
/*******************************************************************************
 *  END OF SIMPLIFIED API
 ******************************************************************************/

3244 3245 3246 3247 3248 3249 3250 3251 3252
#ifdef PNG_CHECK_FOR_INVALID_INDEX_SUPPORTED
PNG_EXPORT(242, void, png_set_check_for_invalid_index,
    (png_structrp png_ptr, int allowed));
#  ifdef PNG_GET_PALETTE_MAX_SUPPORTED
PNG_EXPORT(243, int, png_get_palette_max, (png_const_structp png_ptr,
    png_const_infop info_ptr));
#  endif
#endif /* CHECK_FOR_INVALID_INDEX */

3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277
/*******************************************************************************
 *  IMPLEMENTATION OPTIONS
 *******************************************************************************
 *
 * Support for arbitrary implementation-specific optimizations.  The API allows
 * particular options to be turned on or off.  'Option' is the number of the
 * option and 'onoff' is 0 (off) or non-0 (on).  The value returned is given
 * by the PNG_OPTION_ defines below.
 *
 * HARDWARE: normally hardware capabilites, such as the Intel SSE instructions,
 *           are detected at run time, however sometimes it may be impossible
 *           to do this in user mode, in which case it is necessary to discover
 *           the capabilities in an OS specific way.  Such capabilities are
 *           listed here when libpng has support for them and must be turned
 *           ON by the application if present.
 *
 * SOFTWARE: sometimes software optimizations actually result in performance
 *           decrease on some architectures or systems, or with some sets of
 *           PNG images.  'Software' options allow such optimizations to be
 *           selected at run time.
 */
#ifdef PNG_SET_OPTION_SUPPORTED
#ifdef PNG_ARM_NEON_API_SUPPORTED
#  define PNG_ARM_NEON   0 /* HARDWARE: ARM Neon SIMD instructions supported */
#endif
3278 3279
#define PNG_MAXIMUM_INFLATE_WINDOW 2 /* SOFTWARE: force maximum window */
#define PNG_OPTION_NEXT  4 /* Next option - numbers must be even */
3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294

/* Return values: NOTE: there are four values and 'off' is *not* zero */
#define PNG_OPTION_UNSET   0 /* Unset - defaults to off */
#define PNG_OPTION_INVALID 1 /* Option number out of range */
#define PNG_OPTION_OFF     2
#define PNG_OPTION_ON      3

PNG_EXPORT(244, int, png_set_option, (png_structrp png_ptr, int option,
   int onoff));
#endif

/*******************************************************************************
 *  END OF HARDWARE OPTIONS
 ******************************************************************************/

G
[devel]  
Glenn Randers-Pehrson 已提交
3295
/* Maintainer: Put new public prototypes here ^, in libpng.3, and project
3296
 * defs, scripts/pnglibconf.h, and scripts/pnglibconf.h.prebuilt
G
[devel]  
Glenn Randers-Pehrson 已提交
3297 3298
 */

3299
/* The last ordinal number (this is the *last* one already used; the next
3300 3301
 * one to use is one more than this.)  Maintainer, remember to add an entry to
 * scripts/symbols.def as well.
3302 3303
 */
#ifdef PNG_EXPORT_LAST_ORDINAL
3304
  PNG_EXPORT_LAST_ORDINAL(244);
3305 3306
#endif

A
Andreas Dilger 已提交
3307 3308 3309 3310
#ifdef __cplusplus
}
#endif

3311
#endif /* PNG_VERSION_INFO_ONLY */
3312
/* Do not put anything past this line */
3313
#endif /* PNG_H */