png.h 108 KB
Newer Older
wester committed
1 2 3

/* png.h - header file for PNG reference library
 *
wester committed
4
 * libpng version 1.5.27, May 26, 2016
wester committed
5
 *
wester committed
6
 * Copyright (c) 1998-2002,2004,2006-2016 Glenn Randers-Pehrson
wester committed
7 8 9 10 11 12 13
 * (Version 0.96 Copyright (c) 1996, 1997 Andreas Dilger)
 * (Version 0.88 Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.)
 *
 * This code is released under the libpng license (See LICENSE, below)
 *
 * Authors and maintainers:
 *   libpng versions 0.71, May 1995, through 0.88, January 1996: Guy Schalnat
wester committed
14 15 16
 *   libpng versions 0.89c, June 1996, through 0.96, May 1997: Andreas Dilger
 *   libpng versions 0.97, January 1998, through 1.5.27, May 26, 2016:
 *     Glenn Randers-Pehrson.
wester committed
17 18 19 20 21 22 23 24 25 26 27
 *   See also "Contributing Authors", below.
 */

/*
 * COPYRIGHT NOTICE, DISCLAIMER, and LICENSE:
 *
 * If you modify libpng you may insert additional notices immediately following
 * this sentence.
 *
 * This code is released under the libpng license.
 *
wester committed
28 29
 * libpng versions 1.0.7, July 1, 2000, through 1.5.27, May 26, 2016, are
 * Copyright (c) 2000-2002, 2004, 2006-2016 Glenn Randers-Pehrson, are
wester committed
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 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
 * derived from libpng-1.0.6, and are distributed according to the same
 * disclaimer and license as libpng-1.0.6 with the following individuals
 * added to the list of Contributing Authors:
 *
 *    Simon-Pierre Cadieux
 *    Eric S. Raymond
 *    Mans Rullgard
 *    Cosmin Truta
 *    Gilles Vollant
 *
 * 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
 * Copyright (c) 1998-2000 Glenn Randers-Pehrson, are derived from
 * libpng-0.96, and are distributed according to the same disclaimer and
 * license as libpng-0.96, 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, are derived from libpng-0.88,
 * and are distributed according to the same disclaimer and license as
 * libpng-0.88, with the following individuals added to the list of
 * Contributing Authors:
 *
 *    John Bowler
 *    Kevin Bracey
 *    Sam Bushell
 *    Magnus Holmgren
 *    Greg Roelofs
 *    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
 *    Guy Eric Schalnat
 *    Paul Schmidt
 *    Tim Wegner
 *
 * The PNG Reference Library is supplied "AS IS".  The Contributing Authors
 * and Group 42, Inc. disclaim all warranties, expressed or implied,
 * including, without limitation, the warranties of merchantability and of
 * fitness for any purpose.  The Contributing Authors and Group 42, Inc.
 * assume no liability for direct, indirect, incidental, special, exemplary,
 * 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:
 *
 *   1. The origin of this source code must not be misrepresented.
 *
 *   2. Altered versions must be plainly marked as such and must not
 *      be misrepresented as being the original source.
 *
 *   3. This Copyright notice may not be removed or altered from any
 *      source or altered source distribution.
 *
 * 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.
 *
 * END OF COPYRIGHT NOTICE, DISCLAIMER, and LICENSE.
wester committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133
 *
 * TRADEMARK:
 *
 * The name "libpng" has not been registered by the Copyright owner
 * as a trademark in any jurisdiction.  However, because libpng has
 * been distributed and maintained world-wide, continually since 1995,
 * the Copyright owner claims "common-law trademark protection" in any
 * jurisdiction where common-law trademark is recognized.
 *
 * OSI CERTIFICATION:
 *
 * Libpng is OSI Certified Open Source Software.  OSI Certified Open Source is
 * a certification mark of the Open Source Initiative. OSI has not addressed
 * the additional disclaimers inserted at version 1.0.7.
 *
 * EXPORT CONTROL:
 *
 * The Copyright owner believes that the Export Control Classification
 * Number (ECCN) for libpng is EAR99, which means not subject to export
 * controls or International Traffic in Arms Regulations (ITAR) because
 * it is open source, publicly available software, that does not contain
 * any encryption software.  See the EAR, paragraphs 734.3(b)(3) and
 * 734.7(b).
wester committed
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200
 */

/*
 * A "png_get_copyright" function is available, for convenient use in "about"
 * boxes and the like:
 *
 *    printf("%s", png_get_copyright(NULL));
 *
 * Also, the PNG logo (in PNG format, of course) is supplied in the
 * files "pngbar.png" and "pngbar.jpg (88x31) and "pngnow.png" (98x31).
 */

/*
 * 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.
 */

/* Note about libpng version numbers:
 *
 *    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:
 *
 *    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)
 *    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.19                  10    10019  10.so.0.19[.0]
 *    ...
wester committed
201
 *    1.2.56                  13    10256  12.so.0.56[.0]
wester committed
202
 *    ...
wester committed
203
 *    1.5.27                  15    10527  15.so.15.27[.0]
wester committed
204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230
 *
 *    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
 *    release number plus "betaNN" or "rcNN".
 *
 *    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.
 *
 *    DLLNUM will change each time there are forward or backward changes
 *    in binary compatibility (e.g., when a new feature is added).
 *
 * See libpng.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/
 */

/*
 * Y2K compliance in libpng:
 * =========================
 *
wester committed
231
 *    May 26, 2016
wester committed
232 233 234 235 236
 *
 *    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
wester committed
237
 *    upward through 1.5.27 are Y2K compliant.  It is my belief that
wester committed
238 239 240
 *    earlier versions were also Y2K compliant.
 *
 *    Libpng only has two year fields.  One is a 2-byte unsigned integer
wester committed
241 242
 *    that will hold years up to 65535.  The other holds the date in text
 *    format, and will hold years up to 9999.
wester committed
243 244 245 246 247
 *
 *    The integer is
 *        "png_uint_16 year" in png_time_struct.
 *
 *    The string is
wester committed
248 249
 *        "char time_buffer[29]" in png_struct.  This will be no
 *    longer used in libpng-1.6.0 and will be removed from libpng-1.7.0.
wester committed
250 251
 *
 *    There are seven time-related functions:
wester committed
252 253
 *        png.c: png_convert_to_rfc_1123() in png.c
 *          (formerly png_convert_to_rfc_1152() in error)
wester committed
254 255 256 257 258 259 260 261 262 263
 *        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
wester committed
264 265
 *    the full 4-digit year.  There is a possibility that applications using
 *    libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
wester committed
266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297
 *    function, or that they are incorrectly passing only a 2-digit year
 *    instead of "year - 1900" into the png_convert_from_struct_tm() function,
 *    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
 */

#ifndef PNG_H
#define PNG_H

/* This is not the place to learn how to use libpng. The file libpng-manual.txt
 * 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.  If that
 * file has been stripped from your copy of libpng, you can find it at
 * <http://www.libpng.org/pub/png/libpng-manual.txt>
 *
 * 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'.
 */

/* Version information for png.h - this should match the version in png.c */
wester committed
298
#define PNG_LIBPNG_VER_STRING "1.5.27"
a  
Kai Westerkamp committed
299
#define PNG_HEADER_VERSION_STRING \
wester committed
300
     " libpng version 1.5.27 - May 26, 2016\n"
wester committed
301

wester committed
302 303
#define PNG_LIBPNG_VER_SONUM   15
#define PNG_LIBPNG_VER_DLLNUM  15
wester committed
304 305 306

/* These should match the first 3 components of PNG_LIBPNG_VER_STRING: */
#define PNG_LIBPNG_VER_MAJOR   1
wester committed
307 308
#define PNG_LIBPNG_VER_MINOR   5
#define PNG_LIBPNG_VER_RELEASE 27
wester committed
309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338

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

#define PNG_LIBPNG_VER_BUILD  0

/* Release Status */
#define PNG_LIBPNG_BUILD_ALPHA    1
#define PNG_LIBPNG_BUILD_BETA     2
#define PNG_LIBPNG_BUILD_RC       3
#define PNG_LIBPNG_BUILD_STABLE   4
#define PNG_LIBPNG_BUILD_RELEASE_STATUS_MASK 7

/* 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 */

#define PNG_LIBPNG_BUILD_BASE_TYPE PNG_LIBPNG_BUILD_STABLE

/* 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
 * version 1.0.1 it's    xxyyzz, where x=major, y=minor, z=release
 */
wester committed
339
#define PNG_LIBPNG_VER 10527 /* 1.5.27 */
wester committed
340 341 342 343 344

/* Library configuration: these options cannot be changed after
 * the library has been built.
 */
#ifndef PNGLCONF_H
a  
Kai Westerkamp committed
345 346 347
    /* If pnglibconf.h is missing, you can
     * copy scripts/pnglibconf.h.prebuilt to pnglibconf.h
     */
wester committed
348 349 350 351
#   include "pnglibconf.h"
#endif

#ifndef PNG_VERSION_INFO_ONLY
wester committed
352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370
#  ifndef PNG_BUILDING_SYMBOL_TABLE
  /*
   *   Standard header files (not needed for the version info or while
   *   building symbol table -- see scripts/pnglibconf.dfa)
   */
#    ifdef PNG_SETJMP_SUPPORTED
#      include <setjmp.h>
#    endif

    /* Need the time information for converting tIME chunks, it
     * defines struct tm:
     */
#    ifdef PNG_CONVERT_tIME_SUPPORTED
       /* "time.h" functions are not supported on all operating systems */
#      include <time.h>
#    endif
#  endif

/* Machine specific configuration. */
wester committed
371
#  include "pngconf.h"
wester committed
372
#endif /* PNG_VERSION_INFO_ONLY */
wester committed
373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413

/*
 * Added at libpng-1.2.8
 *
 * Ref MSDN: Private as priority over Special
 * VS_FF_PRIVATEBUILD File *was not* built using standard release
 * procedures. If this value is given, the StringFileInfo block must
 * contain a PrivateBuild string.
 *
 * 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
 * StringFileInfo block must contain a SpecialBuild string.
 */

#ifdef PNG_USER_PRIVATEBUILD /* From pnglibconf.h */
#  define PNG_LIBPNG_BUILD_TYPE \
       (PNG_LIBPNG_BUILD_BASE_TYPE | PNG_LIBPNG_BUILD_PRIVATE)
#else
#  ifdef PNG_LIBPNG_SPECIALBUILD
#    define PNG_LIBPNG_BUILD_TYPE \
         (PNG_LIBPNG_BUILD_BASE_TYPE | PNG_LIBPNG_BUILD_SPECIAL)
#  else
#    define PNG_LIBPNG_BUILD_TYPE (PNG_LIBPNG_BUILD_BASE_TYPE)
#  endif
#endif

#ifndef PNG_VERSION_INFO_ONLY

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

/* Version information for C files, stored in png.c.  This had better match
 * the version above.
 */
#define png_libpng_ver png_get_header_ver(NULL)

/* This file is arranged in several sections:
 *
wester committed
414
 * 1. Any configuration options that can be specified by for the application
wester committed
415
 *    code when it is built.  (Build time configuration is in pnglibconf.h)
wester committed
416
 * 2. Type definitions (base types are defined in pngconf.h), structure
wester committed
417
 *    definitions.
wester committed
418
 * 3. Exported library functions.
wester committed
419 420 421 422
 *
 * The library source code has additional files (principally pngpriv.h) that
 * allow configuration of the library.
 */
wester committed
423
/* Section 1: run time configuration
wester committed
424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452
 * See pnglibconf.h for build time configuration
 *
 * Run time configuration allows the application to choose between
 * implementations of certain arithmetic APIs.  The default is set
 * at build time and recorded in pnglibconf.h, but it is safe to
 * 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.
 */

wester committed
453
/* Section 2: type definitions, including structures and compile time
wester committed
454 455 456 457 458 459 460
 * constants.
 * See pngconf.h for base types that vary by machine/system
 */

/* This triggers a compiler error in png.c, if png.c and png.h
 * do not agree upon the version number.
 */
wester committed
461
typedef char* png_libpng_version_1_5_27;
wester committed
462 463 464 465 466 467 468 469 470 471 472

/* 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).
 */
typedef struct png_color_struct
{
   png_byte red;
   png_byte green;
   png_byte blue;
} png_color;
wester committed
473 474 475
typedef png_color FAR * png_colorp;
typedef PNG_CONST png_color FAR * png_const_colorp;
typedef png_color FAR * FAR * png_colorpp;
wester committed
476 477 478 479 480 481 482 483 484

typedef struct png_color_16_struct
{
   png_byte index;    /* used for palette files */
   png_uint_16 red;   /* for use in red green blue files */
   png_uint_16 green;
   png_uint_16 blue;
   png_uint_16 gray;  /* for use in grayscale files */
} png_color_16;
wester committed
485 486 487
typedef png_color_16 FAR * png_color_16p;
typedef PNG_CONST png_color_16 FAR * png_const_color_16p;
typedef png_color_16 FAR * FAR * png_color_16pp;
wester committed
488 489 490 491 492 493 494 495 496

typedef struct png_color_8_struct
{
   png_byte red;   /* for use in red green blue files */
   png_byte green;
   png_byte blue;
   png_byte gray;  /* for use in grayscale files */
   png_byte alpha; /* for alpha channel files */
} png_color_8;
wester committed
497 498 499
typedef png_color_8 FAR * png_color_8p;
typedef PNG_CONST png_color_8 FAR * png_const_color_8p;
typedef png_color_8 FAR * FAR * png_color_8pp;
wester committed
500 501 502 503 504 505 506 507 508 509 510 511 512

/*
 * The following two structures are used for the in-core representation
 * of sPLT chunks.
 */
typedef struct png_sPLT_entry_struct
{
   png_uint_16 red;
   png_uint_16 green;
   png_uint_16 blue;
   png_uint_16 alpha;
   png_uint_16 frequency;
} png_sPLT_entry;
wester committed
513 514 515
typedef png_sPLT_entry FAR * png_sPLT_entryp;
typedef PNG_CONST png_sPLT_entry FAR * png_const_sPLT_entryp;
typedef png_sPLT_entry FAR * FAR * png_sPLT_entrypp;
wester committed
516 517 518 519 520 521 522 523 524 525 526 527 528

/*  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.
 */

typedef struct png_sPLT_struct
{
   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 */
} png_sPLT_t;
wester committed
529 530 531
typedef png_sPLT_t FAR * png_sPLT_tp;
typedef PNG_CONST png_sPLT_t FAR * png_const_sPLT_tp;
typedef png_sPLT_t FAR * FAR * png_sPLT_tpp;
wester committed
532 533 534 535 536 537 538 539 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

#ifdef PNG_TEXT_SUPPORTED
/* png_text holds the contents of a text/ztxt/itxt chunk in a PNG file,
 * and whether that contents is compressed or not.  The "key" field
 * points to a regular zero-terminated C string.  The "text" fields can be a
 * regular C string, an empty string, or a NULL pointer.
 * However, the structure returned by png_get_text() will always contain
 * 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
 * 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.
 */
typedef struct png_text_struct
{
   int  compression;       /* compression value:
                             -1: tEXt, none
                              0: zTXt, deflate
                              1: iTXt, none
                              2: iTXt, deflate  */
   png_charp key;          /* keyword, 1-79 character description of "text" */
   png_charp text;         /* comment, may be an empty string (ie "")
                              or a NULL pointer */
   png_size_t text_length; /* length of the text string */
   png_size_t itxt_length; /* length of the itxt string */
   png_charp lang;         /* language code, 0-79 characters
                              or a NULL pointer */
   png_charp lang_key;     /* keyword translated UTF-8 string, 0 or more
                              chars or a NULL pointer */
} png_text;
wester committed
568 569 570
typedef png_text FAR * png_textp;
typedef PNG_CONST png_text FAR * png_const_textp;
typedef png_text FAR * FAR * png_textpp;
wester committed
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597
#endif

/* 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
#define PNG_ITXT_COMPRESSION_NONE     1
#define PNG_ITXT_COMPRESSION_zTXt     2
#define PNG_TEXT_COMPRESSION_LAST     3  /* Not a valid value */

/* png_time is a way to hold the time in an machine independent way.
 * 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
 * note - PNG has always been Year 2000 compliant!
 */
typedef struct png_time_struct
{
   png_uint_16 year; /* full year, as in, 1995 */
   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) */
} png_time;
wester committed
598 599 600
typedef png_time FAR * png_timep;
typedef PNG_CONST png_time FAR * png_const_timep;
typedef png_time FAR * FAR * png_timepp;
wester committed
601

wester committed
602 603
#if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) || \
    defined(PNG_HANDLE_AS_UNKNOWN_SUPPORTED)
wester committed
604 605 606 607 608 609 610
/* 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.
 */
typedef struct png_unknown_chunk_t
{
wester committed
611 612
    png_byte name[5];
    png_byte *data;
a  
Kai Westerkamp committed
613 614
    png_size_t size;

wester committed
615
    /* libpng-using applications should NOT directly modify this byte. */
a  
Kai Westerkamp committed
616
    png_byte location; /* mode of operation at read time */
wester committed
617 618
}

wester committed
619 620 621 622 623

png_unknown_chunk;
typedef png_unknown_chunk FAR * png_unknown_chunkp;
typedef PNG_CONST png_unknown_chunk FAR * png_const_unknown_chunkp;
typedef png_unknown_chunk FAR * FAR * png_unknown_chunkpp;
wester committed
624 625
#endif

wester committed
626 627
/* Values for the unknown chunk location byte */

wester committed
628 629 630 631
#define PNG_HAVE_IHDR  0x01
#define PNG_HAVE_PLTE  0x02
#define PNG_AFTER_IDAT 0x08

wester committed
632 633 634 635 636 637 638 639 640
/* The complete definition of png_info has, as of libpng-1.5.0,
 * 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 FAR * png_infop;
typedef PNG_CONST png_info FAR * png_const_infop;
typedef png_info FAR * FAR * png_infopp;

wester committed
641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724
/* Maximum positive integer used in PNG is (2^31)-1 */
#define PNG_UINT_31_MAX ((png_uint_32)0x7fffffffL)
#define PNG_UINT_32_MAX ((png_uint_32)(-1))
#define PNG_SIZE_MAX ((png_size_t)(-1))

/* These are constants for fixed point values encoded in the
 * PNG specification manner (x100000)
 */
#define PNG_FP_1    100000
#define PNG_FP_HALF  50000
#define PNG_FP_MAX  ((png_fixed_point)0x7fffffffL)
#define PNG_FP_MIN  (-PNG_FP_MAX)

/* These describe the color_type field in png_info. */
/* color type masks */
#define PNG_COLOR_MASK_PALETTE    1
#define PNG_COLOR_MASK_COLOR      2
#define PNG_COLOR_MASK_ALPHA      4

/* color types.  Note that not all combinations are legal */
#define PNG_COLOR_TYPE_GRAY 0
#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)
#define PNG_COLOR_TYPE_GRAY_ALPHA (PNG_COLOR_MASK_ALPHA)
/* aliases */
#define PNG_COLOR_TYPE_RGBA  PNG_COLOR_TYPE_RGB_ALPHA
#define PNG_COLOR_TYPE_GA  PNG_COLOR_TYPE_GRAY_ALPHA

/* This is for compression type. PNG 1.0-1.2 only define the single type. */
#define PNG_COMPRESSION_TYPE_BASE 0 /* Deflate method 8, 32K window */
#define PNG_COMPRESSION_TYPE_DEFAULT PNG_COMPRESSION_TYPE_BASE

/* This is for filter type. PNG 1.0-1.2 only define the single type. */
#define PNG_FILTER_TYPE_BASE      0 /* Single row per-byte filtering */
#define PNG_INTRAPIXEL_DIFFERENCING 64 /* Used only in MNG datastreams */
#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 */

/* 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 */

/* 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 */

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

/* This is for text chunks */
#define PNG_KEYWORD_MAX_LENGTH     79

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

/* 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.
 */
wester committed
725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740
#define PNG_INFO_gAMA 0x0001U
#define PNG_INFO_sBIT 0x0002U
#define PNG_INFO_cHRM 0x0004U
#define PNG_INFO_PLTE 0x0008U
#define PNG_INFO_tRNS 0x0010U
#define PNG_INFO_bKGD 0x0020U
#define PNG_INFO_hIST 0x0040U
#define PNG_INFO_pHYs 0x0080U
#define PNG_INFO_oFFs 0x0100U
#define PNG_INFO_tIME 0x0200U
#define PNG_INFO_pCAL 0x0400U
#define PNG_INFO_sRGB 0x0800U  /* GR-P, 0.96a */
#define PNG_INFO_iCCP 0x1000U  /* ESR, 1.0.6 */
#define PNG_INFO_sPLT 0x2000U  /* ESR, 1.0.6 */
#define PNG_INFO_sCAL 0x4000U  /* ESR, 1.0.6 */
#define PNG_INFO_IDAT 0x8000U  /* ESR, 1.0.6 */
wester committed
741 742 743 744 745 746 747 748 749 750 751 752 753 754 755

/* 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.
 */
typedef struct png_row_info_struct
{
   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) */
   png_byte pixel_depth; /* bits per pixel (depth * channels) */
} png_row_info;

wester committed
756 757 758 759 760 761 762 763 764 765
typedef png_row_info FAR * png_row_infop;
typedef png_row_info FAR * FAR * png_row_infopp;

/* The complete definition of png_struct has, as of libpng-1.5.0,
 * 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_struct_def png_struct;
typedef PNG_CONST png_struct FAR * png_const_structp;
typedef png_struct FAR * png_structp;
wester committed
766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811

/* 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
 * user read/write data functions.  Note that the 'write' function must not
 * modify the buffer it is passed. The 'read' function, on the other hand, is
 * expected to return the read data in the buffer.
 */
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));

#ifdef PNG_PROGRESSIVE_READ_SUPPORTED
typedef PNG_CALLBACK(void, *png_progressive_info_ptr, (png_structp, png_infop));
typedef PNG_CALLBACK(void, *png_progressive_end_ptr, (png_structp, png_infop));

/* 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.)
 */
typedef PNG_CALLBACK(void, *png_progressive_row_ptr, (png_structp, png_bytep,
    png_uint_32, int));
#endif

#if defined(PNG_READ_USER_TRANSFORM_SUPPORTED) || \
    defined(PNG_WRITE_USER_TRANSFORM_SUPPORTED)
typedef PNG_CALLBACK(void, *png_user_transform_ptr, (png_structp, png_row_infop,
    png_bytep));
#endif

#ifdef PNG_USER_CHUNKS_SUPPORTED
typedef PNG_CALLBACK(int, *png_user_chunk_ptr, (png_structp,
    png_unknown_chunkp));
#endif
#ifdef PNG_UNKNOWN_CHUNKS_SUPPORTED
wester committed
812
typedef PNG_CALLBACK(void, *png_unknown_chunk_ptr, (png_structp));
wester committed
813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867
#endif

#ifdef PNG_SETJMP_SUPPORTED
/* 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
 * 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!
 */
PNG_FUNCTION(void, (PNGCAPI *png_longjmp_ptr), PNGARG((jmp_buf, int)), typedef);
#endif

/* Transform masks for the high-level interface */
#define PNG_TRANSFORM_IDENTITY       0x0000    /* read and write */
#define PNG_TRANSFORM_STRIP_16       0x0001    /* read only */
#define PNG_TRANSFORM_STRIP_ALPHA    0x0002    /* read only */
#define PNG_TRANSFORM_PACKING        0x0004    /* read and write */
#define PNG_TRANSFORM_PACKSWAP       0x0008    /* read and write */
#define PNG_TRANSFORM_EXPAND         0x0010    /* read only */
#define PNG_TRANSFORM_INVERT_MONO    0x0020    /* read and write */
#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 */
#define PNG_TRANSFORM_SWAP_ENDIAN    0x0200    /* read and write */
#define PNG_TRANSFORM_INVERT_ALPHA   0x0400    /* read and write */
#define PNG_TRANSFORM_STRIP_FILLER   0x0800    /* write only */
/* Added to libpng-1.2.34 */
#define PNG_TRANSFORM_STRIP_FILLER_BEFORE PNG_TRANSFORM_STRIP_FILLER
#define PNG_TRANSFORM_STRIP_FILLER_AFTER 0x1000 /* write only */
/* Added to libpng-1.4.0 */
#define PNG_TRANSFORM_GRAY_TO_RGB   0x2000      /* read only */
/* Added to libpng-1.5.4 */
#define PNG_TRANSFORM_EXPAND_16     0x4000      /* read only */
#define PNG_TRANSFORM_SCALE_16      0x8000      /* read only */

/* Flags for MNG supported features */
#define PNG_FLAG_MNG_EMPTY_PLTE     0x01
#define PNG_FLAG_MNG_FILTER_64      0x04
#define PNG_ALL_MNG_FEATURES        0x05

/* NOTE: prior to 1.5 these functions had no 'API' style declaration,
 * 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.
 */
typedef PNG_CALLBACK(png_voidp, *png_malloc_ptr, (png_structp,
    png_alloc_size_t));
typedef PNG_CALLBACK(void, *png_free_ptr, (png_structp, png_voidp));

wester committed
868 869 870
typedef png_struct FAR * FAR * png_structpp;

/* Section 3: exported functions
wester committed
871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904
 * Here are the function definitions most commonly used.  This is not
 * the place to find out how to use libpng.  See libpng-manual.txt for the
 * full explanation, see example.c for the summary.  This just provides
 * a simple one line description of the use of each function.
 *
 * The PNG_EXPORT() and PNG_EXPORTA() macros used below are defined in
 * pngconf.h and in the *.dfn files in the scripts directory.
 *
 *   PNG_EXPORT(ordinal, type, name, (args));
 *
 *       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
 *                   entries, and are removed by pngconf.h.
 *       type:       return type of the function
 *       name:       function name
 *       args:       function arguments, with types
 *
 * When we wish to append attributes to a function prototype we use
 * the PNG_EXPORTA() macro instead.
 *
 *   PNG_EXPORTA(ordinal, type, name, (args), attributes);
 *
 *       ordinal, type, name, and args: same as in PNG_EXPORT().
 *       attributes: function attributes
 */

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

/* Tell lib we have already handled the first <num_bytes> magic bytes.
 * Handling more than 8 bytes from the beginning of the file is an error.
 */
wester committed
905
PNG_EXPORT(2, void, png_set_sig_bytes, (png_structp png_ptr, int num_bytes));
wester committed
906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931

/* 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).
 */
PNG_EXPORT(3, int, png_sig_cmp, (png_const_bytep sig, png_size_t start,
    png_size_t num_to_check));

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

/* Allocate and initialize png_ptr struct for reading, and any other memory. */
PNG_EXPORTA(4, png_structp, png_create_read_struct,
    (png_const_charp user_png_ver, png_voidp error_ptr,
    png_error_ptr error_fn, png_error_ptr warn_fn),
    PNG_ALLOCATED);

/* Allocate and initialize png_ptr struct for writing, and any other memory */
PNG_EXPORTA(5, png_structp, png_create_write_struct,
    (png_const_charp user_png_ver, png_voidp error_ptr, png_error_ptr error_fn,
    png_error_ptr warn_fn),
    PNG_ALLOCATED);

wester committed
932
#ifdef PNG_WRITE_CUSTOMIZE_COMPRESSION_SUPPORTED
wester committed
933
PNG_EXPORT(6, png_size_t, png_get_compression_buffer_size,
wester committed
934
    (png_const_structp png_ptr));
wester committed
935

wester committed
936
PNG_EXPORT(7, void, png_set_compression_buffer_size, (png_structp png_ptr,
wester committed
937
    png_size_t size));
wester committed
938
#endif /* WRITE_CUSTOMIZE_COMPRESSION */
wester committed
939 940 941 942 943 944 945 946 947 948 949 950

/* 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.
 */
wester committed
951
PNG_EXPORT(8, jmp_buf*, png_set_longjmp_fn, (png_structp png_ptr,
wester committed
952 953
    png_longjmp_ptr longjmp_fn, size_t jmp_buf_size));
#  define png_jmpbuf(png_ptr) \
wester committed
954
      (*png_set_longjmp_fn((png_ptr), longjmp, sizeof (jmp_buf)))
wester committed
955 956 957 958 959 960 961 962 963
#else
#  define png_jmpbuf(png_ptr) \
      (LIBPNG_WAS_COMPILED_WITH__PNG_NO_SETJMP)
#endif
/* 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.
 */
wester committed
964
PNG_EXPORTA(9, void, png_longjmp, (png_structp png_ptr, int val),
wester committed
965 966 967 968
    PNG_NORETURN);

#ifdef PNG_READ_SUPPORTED
/* Reset the compression stream */
wester committed
969
PNG_EXPORT(10, int, png_reset_zstream, (png_structp png_ptr));
wester committed
970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986
#endif

/* New functions added in libpng-1.0.2 (not enabled by default until 1.2.0) */
#ifdef PNG_USER_MEM_SUPPORTED
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,
    png_error_ptr warn_fn,
    png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn),
    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,
    png_error_ptr warn_fn,
    png_voidp mem_ptr, png_malloc_ptr malloc_fn, png_free_ptr free_fn),
    PNG_ALLOCATED);
#endif

/* Write the PNG file signature. */
wester committed
987
PNG_EXPORT(13, void, png_write_sig, (png_structp png_ptr));
wester committed
988 989

/* Write a PNG chunk - size, type, (optional) data, CRC. */
wester committed
990
PNG_EXPORT(14, void, png_write_chunk, (png_structp png_ptr, png_const_bytep
wester committed
991 992 993
    chunk_name, png_const_bytep data, png_size_t length));

/* Write the start of a PNG chunk - length and chunk name. */
wester committed
994
PNG_EXPORT(15, void, png_write_chunk_start, (png_structp png_ptr,
wester committed
995 996 997
    png_const_bytep chunk_name, png_uint_32 length));

/* Write the data of a PNG chunk started with png_write_chunk_start(). */
wester committed
998
PNG_EXPORT(16, void, png_write_chunk_data, (png_structp png_ptr,
wester committed
999 1000 1001
    png_const_bytep data, png_size_t length));

/* Finish a chunk started with png_write_chunk_start() (includes CRC). */
wester committed
1002
PNG_EXPORT(17, void, png_write_chunk_end, (png_structp png_ptr));
wester committed
1003 1004

/* Allocate and initialize the info structure */
wester committed
1005
PNG_EXPORTA(18, png_infop, png_create_info_struct, (png_structp png_ptr),
wester committed
1006 1007
    PNG_ALLOCATED);

wester committed
1008 1009
PNG_EXPORT(19, void, png_info_init_3, (png_infopp info_ptr,
    png_size_t png_info_struct_size));
wester committed
1010 1011 1012

/* Writes all the PNG information before the image. */
PNG_EXPORT(20, void, png_write_info_before_PLTE,
wester committed
1013
    (png_structp png_ptr, png_infop info_ptr));
wester committed
1014
PNG_EXPORT(21, void, png_write_info,
wester committed
1015
    (png_structp png_ptr, png_infop info_ptr));
wester committed
1016 1017 1018 1019

#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
/* Read the information before the actual image data. */
PNG_EXPORT(22, void, png_read_info,
wester committed
1020
    (png_structp png_ptr, png_infop info_ptr));
wester committed
1021 1022 1023
#endif

#ifdef PNG_TIME_RFC1123_SUPPORTED
wester committed
1024 1025
PNG_EXPORT(23, png_const_charp, png_convert_to_rfc1123,
    (png_structp png_ptr,
wester committed
1026 1027 1028 1029 1030 1031
    png_const_timep ptime));
#endif

#ifdef PNG_CONVERT_tIME_SUPPORTED
/* Convert from a struct tm to png_time */
PNG_EXPORT(24, void, png_convert_from_struct_tm, (png_timep ptime,
wester committed
1032
    PNG_CONST struct tm FAR * ttime));
wester committed
1033 1034

/* Convert from time_t to png_time.  Uses gmtime() */
wester committed
1035 1036 1037
PNG_EXPORT(25, void, png_convert_from_time_t,
    (png_timep ptime, time_t ttime));
#endif /* PNG_CONVERT_tIME_SUPPORTED */
wester committed
1038 1039 1040

#ifdef PNG_READ_EXPAND_SUPPORTED
/* Expand data to 24-bit RGB, or 8-bit grayscale, with alpha if available. */
wester committed
1041 1042 1043 1044
PNG_EXPORT(26, void, png_set_expand, (png_structp png_ptr));
PNG_EXPORT(27, void, png_set_expand_gray_1_2_4_to_8, (png_structp png_ptr));
PNG_EXPORT(28, void, png_set_palette_to_rgb, (png_structp png_ptr));
PNG_EXPORT(29, void, png_set_tRNS_to_alpha, (png_structp png_ptr));
wester committed
1045 1046 1047 1048 1049 1050
#endif

#ifdef PNG_READ_EXPAND_16_SUPPORTED
/* Expand to 16-bit channels, forces conversion of palette to RGB and expansion
 * of a tRNS chunk if present.
 */
wester committed
1051
PNG_EXPORT(221, void, png_set_expand_16, (png_structp png_ptr));
wester committed
1052 1053 1054 1055
#endif

#if defined(PNG_READ_BGR_SUPPORTED) || defined(PNG_WRITE_BGR_SUPPORTED)
/* Use blue, green, red order for pixels. */
wester committed
1056
PNG_EXPORT(30, void, png_set_bgr, (png_structp png_ptr));
wester committed
1057 1058 1059 1060
#endif

#ifdef PNG_READ_GRAY_TO_RGB_SUPPORTED
/* Expand the grayscale to 24-bit RGB if necessary. */
wester committed
1061
PNG_EXPORT(31, void, png_set_gray_to_rgb, (png_structp png_ptr));
wester committed
1062 1063 1064 1065 1066 1067 1068 1069 1070
#endif

#ifdef PNG_READ_RGB_TO_GRAY_SUPPORTED
/* Reduce RGB to grayscale. */
#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*/

wester committed
1071
PNG_FP_EXPORT(32, void, png_set_rgb_to_gray, (png_structp png_ptr,
wester committed
1072
    int error_action, double red, double green))
wester committed
1073
PNG_FIXED_EXPORT(33, void, png_set_rgb_to_gray_fixed, (png_structp png_ptr,
wester committed
1074 1075
    int error_action, png_fixed_point red, png_fixed_point green))

wester committed
1076
PNG_EXPORT(34, png_byte, png_get_rgb_to_gray_status, (png_const_structp
wester committed
1077 1078 1079 1080 1081 1082 1083 1084 1085
    png_ptr));
#endif

#ifdef PNG_BUILD_GRAYSCALE_PALETTE_SUPPORTED
PNG_EXPORT(35, void, png_build_grayscale_palette, (int bit_depth,
    png_colorp palette));
#endif

#ifdef PNG_READ_ALPHA_MODE_SUPPORTED
wester committed
1086 1087 1088
/* How the alpha channel is interpreted - this affects how the color channels of
 * a PNG file are returned when an alpha channel, or tRNS chunk in a palette
 * file, is present.
wester committed
1089 1090 1091 1092 1093 1094 1095
 *
 * 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
 * channel is a linear measure of the contribution of the pixel to the
wester committed
1096 1097
 * corresponding composited pixel.  The gamma encoded color channels must be
 * scaled according to the contribution and to do this it is necessary to undo
wester committed
1098 1099 1100 1101
 * the encoding, scale the color values, perform the composition and reencode
 * the values.  This is the 'PNG' mode.
 *
 * The alternative is to 'associate' the alpha with the color information by
wester committed
1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122
 * 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
 * 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
 * gamma encoding is used.  In addition all non-transparent pixel values,
 * including completely opaque ones, must be gamma encoded to produce the final
 * image.  This is the 'STANDARD', 'ASSOCIATED' or 'PREMULTIPLIED' mode (the
 * 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
 * isolated, therefore typically the accuracy loss in storing 8-bit linear
 * values is acceptable.  (This is not true if the alpha channel is used to
 * 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
 * treated as opaque only if the alpha value is equal to the maximum value.
wester committed
1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140
 *
 * 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
 * with an enumerated 'mode' value and the gamma of the required output:
 */
#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 */

wester committed
1141
PNG_FP_EXPORT(227, void, png_set_alpha_mode, (png_structp png_ptr, int mode,
wester committed
1142
    double output_gamma))
wester committed
1143
PNG_FIXED_EXPORT(228, void, png_set_alpha_mode_fixed, (png_structp png_ptr,
wester committed
1144 1145 1146
    int mode, png_fixed_point output_gamma))
#endif

wester committed
1147
#if defined(PNG_READ_GAMMA_SUPPORTED) || defined(PNG_READ_ALPHA_MODE_SUPPORTED)
wester committed
1148
/* The output_gamma value is a screen gamma in libpng terminology: it expresses
wester committed
1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210
 * 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!
 *
 * 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.
 *
 * 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.
wester committed
1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 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
 */
#define PNG_DEFAULT_sRGB -1       /* sRGB gamma and color space */
#define PNG_GAMMA_MAC_18 -2       /* Old Mac '1.8' gamma and color space */
#define PNG_GAMMA_sRGB   220000   /* Television standards--matches sRGB gamma */
#define PNG_GAMMA_LINEAR PNG_FP_1 /* Linear */
#endif

/* 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.
 *
 * png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_GAMMA_LINEAR);
 *    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
 *    below then encode the resultant 8-bit or 16-bit values to match the output
 *    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.
 */

#ifdef PNG_READ_STRIP_ALPHA_SUPPORTED
wester committed
1295
PNG_EXPORT(36, void, png_set_strip_alpha, (png_structp png_ptr));
wester committed
1296 1297 1298 1299
#endif

#if defined(PNG_READ_SWAP_ALPHA_SUPPORTED) || \
    defined(PNG_WRITE_SWAP_ALPHA_SUPPORTED)
wester committed
1300
PNG_EXPORT(37, void, png_set_swap_alpha, (png_structp png_ptr));
wester committed
1301 1302 1303 1304
#endif

#if defined(PNG_READ_INVERT_ALPHA_SUPPORTED) || \
    defined(PNG_WRITE_INVERT_ALPHA_SUPPORTED)
wester committed
1305
PNG_EXPORT(38, void, png_set_invert_alpha, (png_structp png_ptr));
wester committed
1306 1307 1308
#endif

#if defined(PNG_READ_FILLER_SUPPORTED) || defined(PNG_WRITE_FILLER_SUPPORTED)
wester committed
1309 1310
/* Add a filler byte to 8-bit Gray or 24-bit RGB images. */
PNG_EXPORT(39, void, png_set_filler, (png_structp png_ptr, png_uint_32 filler,
wester committed
1311 1312 1313 1314
    int flags));
/* The values of the PNG_FILLER_ defines should NOT be changed */
#  define PNG_FILLER_BEFORE 0
#  define PNG_FILLER_AFTER 1
wester committed
1315 1316 1317 1318 1319
/* Add an alpha byte to 8-bit Gray or 24-bit RGB images. */
PNG_EXPORT(40, void, png_set_add_alpha,
    (png_structp png_ptr, png_uint_32 filler,
    int flags));
#endif /* PNG_READ_FILLER_SUPPORTED || PNG_WRITE_FILLER_SUPPORTED */
wester committed
1320 1321 1322

#if defined(PNG_READ_SWAP_SUPPORTED) || defined(PNG_WRITE_SWAP_SUPPORTED)
/* Swap bytes in 16-bit depth files. */
wester committed
1323
PNG_EXPORT(41, void, png_set_swap, (png_structp png_ptr));
wester committed
1324 1325 1326 1327
#endif

#if defined(PNG_READ_PACK_SUPPORTED) || defined(PNG_WRITE_PACK_SUPPORTED)
/* Use 1 byte per pixel in 1, 2, or 4-bit depth files. */
wester committed
1328
PNG_EXPORT(42, void, png_set_packing, (png_structp png_ptr));
wester committed
1329 1330 1331 1332 1333
#endif

#if defined(PNG_READ_PACKSWAP_SUPPORTED) || \
    defined(PNG_WRITE_PACKSWAP_SUPPORTED)
/* Swap packing order of pixels in bytes. */
wester committed
1334
PNG_EXPORT(43, void, png_set_packswap, (png_structp png_ptr));
wester committed
1335 1336 1337 1338
#endif

#if defined(PNG_READ_SHIFT_SUPPORTED) || defined(PNG_WRITE_SHIFT_SUPPORTED)
/* Converts files to legal bit depths. */
wester committed
1339
PNG_EXPORT(44, void, png_set_shift, (png_structp png_ptr, png_const_color_8p
wester committed
1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350
    true_bits));
#endif

#if defined(PNG_READ_INTERLACING_SUPPORTED) || \
    defined(PNG_WRITE_INTERLACING_SUPPORTED)
/* Have the code handle the interlacing.  Returns the number of passes.
 * 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.
*/
wester committed
1351
PNG_EXPORT(45, int, png_set_interlace_handling, (png_structp png_ptr));
wester committed
1352 1353 1354 1355
#endif

#if defined(PNG_READ_INVERT_SUPPORTED) || defined(PNG_WRITE_INVERT_SUPPORTED)
/* Invert monochrome files */
wester committed
1356
PNG_EXPORT(46, void, png_set_invert_mono, (png_structp png_ptr));
wester committed
1357 1358 1359 1360 1361 1362 1363 1364
#endif

#ifdef PNG_READ_BACKGROUND_SUPPORTED
/* Handle alpha and tRNS by replacing with a background color.  Prior to
 * libpng-1.5.4 this API must not be called before the PNG file header has been
 * read.  Doing so will result in unexpected behavior and possible warnings or
 * errors if the PNG file contains a bKGD chunk.
 */
wester committed
1365
PNG_FP_EXPORT(47, void, png_set_background, (png_structp png_ptr,
wester committed
1366 1367
    png_const_color_16p background_color, int background_gamma_code,
    int need_expand, double background_gamma))
wester committed
1368
PNG_FIXED_EXPORT(215, void, png_set_background_fixed, (png_structp png_ptr,
wester committed
1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380
    png_const_color_16p background_color, int background_gamma_code,
    int need_expand, png_fixed_point background_gamma))
#endif
#ifdef PNG_READ_BACKGROUND_SUPPORTED
#  define PNG_BACKGROUND_GAMMA_UNKNOWN 0
#  define PNG_BACKGROUND_GAMMA_SCREEN  1
#  define PNG_BACKGROUND_GAMMA_FILE    2
#  define PNG_BACKGROUND_GAMMA_UNIQUE  3
#endif

#ifdef PNG_READ_SCALE_16_TO_8_SUPPORTED
/* Scale a 16-bit depth file down to 8-bit, accurately. */
wester committed
1381
PNG_EXPORT(229, void, png_set_scale_16, (png_structp png_ptr));
wester committed
1382 1383 1384
#endif

#ifdef PNG_READ_STRIP_16_TO_8_SUPPORTED
wester committed
1385
#define PNG_READ_16_TO_8_SUPPORTED /* Name prior to 1.5.4 */
wester committed
1386
/* Strip the second byte of information from a 16-bit depth file. */
wester committed
1387
PNG_EXPORT(48, void, png_set_strip_16, (png_structp png_ptr));
wester committed
1388 1389 1390 1391 1392 1393
#endif

#ifdef PNG_READ_QUANTIZE_SUPPORTED
/* Turn on quantizing, and reduce the palette to the number of colors
 * available.
 */
wester committed
1394 1395 1396 1397
PNG_EXPORT(49, void, png_set_quantize,
    (png_structp png_ptr, png_colorp palette,
    int num_palette, int maximum_colors, png_const_uint_16p histogram,
    int full_quantize));
wester committed
1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416
#endif

#ifdef PNG_READ_GAMMA_SUPPORTED
/* 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)

/* Handle gamma correction. Screen_gamma=(display_exponent).
 * NOTE: this API simply sets the screen and file gamma values. It will
 * therefore override the value for gamma in a PNG file if it is called after
 * 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.
 */
wester committed
1417 1418 1419 1420
PNG_FP_EXPORT(50, void, png_set_gamma,
    (png_structp png_ptr, double screen_gamma,
    double override_file_gamma))
PNG_FIXED_EXPORT(208, void, png_set_gamma_fixed, (png_structp png_ptr,
wester committed
1421 1422 1423 1424 1425
    png_fixed_point screen_gamma, png_fixed_point override_file_gamma))
#endif

#ifdef PNG_WRITE_FLUSH_SUPPORTED
/* Set how many lines between output flushes - 0 for no flushing */
wester committed
1426
PNG_EXPORT(51, void, png_set_flush, (png_structp png_ptr, int nrows));
wester committed
1427
/* Flush the current PNG output buffer */
wester committed
1428
PNG_EXPORT(52, void, png_write_flush, (png_structp png_ptr));
wester committed
1429 1430 1431
#endif

/* Optional update palette with requested transformations */
wester committed
1432
PNG_EXPORT(53, void, png_start_read_image, (png_structp png_ptr));
wester committed
1433 1434

/* Optional call to update the users info structure */
wester committed
1435 1436
PNG_EXPORT(54, void, png_read_update_info,
    (png_structp png_ptr, png_infop info_ptr));
wester committed
1437 1438 1439

#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
/* Read one or more rows of image data. */
wester committed
1440
PNG_EXPORT(55, void, png_read_rows, (png_structp png_ptr, png_bytepp row,
wester committed
1441 1442 1443 1444 1445
    png_bytepp display_row, png_uint_32 num_rows));
#endif

#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
/* Read a row of data. */
wester committed
1446
PNG_EXPORT(56, void, png_read_row, (png_structp png_ptr, png_bytep row,
wester committed
1447 1448 1449 1450 1451
    png_bytep display_row));
#endif

#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
/* Read the whole image into memory at once. */
wester committed
1452
PNG_EXPORT(57, void, png_read_image, (png_structp png_ptr, png_bytepp image));
wester committed
1453 1454 1455
#endif

/* Write a row of image data */
wester committed
1456 1457
PNG_EXPORT(58, void, png_write_row,
    (png_structp png_ptr, png_const_bytep row));
wester committed
1458 1459 1460 1461 1462 1463

/* 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
 * unchanged to write_rows.
 */
wester committed
1464
PNG_EXPORT(59, void, png_write_rows, (png_structp png_ptr, png_bytepp row,
wester committed
1465 1466 1467
    png_uint_32 num_rows));

/* Write the image data */
wester committed
1468 1469
PNG_EXPORT(60, void, png_write_image,
    (png_structp png_ptr, png_bytepp image));
wester committed
1470 1471

/* Write the end of the PNG file. */
wester committed
1472 1473
PNG_EXPORT(61, void, png_write_end,
    (png_structp png_ptr, png_infop info_ptr));
wester committed
1474 1475 1476

#ifdef PNG_SEQUENTIAL_READ_SUPPORTED
/* Read the end of the PNG file. */
wester committed
1477
PNG_EXPORT(62, void, png_read_end, (png_structp png_ptr, png_infop info_ptr));
wester committed
1478 1479 1480
#endif

/* Free any memory associated with the png_info_struct */
wester committed
1481
PNG_EXPORT(63, void, png_destroy_info_struct, (png_structp png_ptr,
wester committed
1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492
    png_infopp info_ptr_ptr));

/* Free any memory associated with the png_struct and the png_info_structs */
PNG_EXPORT(64, void, png_destroy_read_struct, (png_structpp png_ptr_ptr,
    png_infopp info_ptr_ptr, png_infopp end_info_ptr_ptr));

/* Free any memory associated with the png_struct and the png_info_structs */
PNG_EXPORT(65, void, png_destroy_write_struct, (png_structpp png_ptr_ptr,
    png_infopp info_ptr_ptr));

/* Set the libpng method of handling chunk CRC errors */
wester committed
1493 1494
PNG_EXPORT(66, void, png_set_crc_action,
    (png_structp png_ptr, int crit_action, int ancil_action));
wester committed
1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522

/* Values for png_set_crc_action() say how to handle CRC errors in
 * ancillary and critical chunks, and whether to use the data contained
 * therein.  Note that it is impossible to "discard" data in a critical
 * chunk.  For versions prior to 0.90, the action was always error/quit,
 * 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
 */
#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 */

/* 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
 * header file (zlib.h) for an explination of the compression functions.
 */

/* Set the filtering method(s) used by libpng.  Currently, the only valid
 * value for "method" is 0.
 */
wester committed
1523 1524
PNG_EXPORT(67, void, png_set_filter,
    (png_structp png_ptr, int method, int filters));
wester committed
1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536

/* Flags for png_set_filter() to say which filters to use.  The flags
 * 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.
 */
#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
wester committed
1537 1538
#define PNG_FAST_FILTERS (PNG_FILTER_NONE | PNG_FILTER_SUB | PNG_FILTER_UP)
#define PNG_ALL_FILTERS (PNG_FAST_FILTERS | PNG_FILTER_AVG | PNG_FILTER_PAETH)
wester committed
1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550

/* 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

#ifdef PNG_WRITE_WEIGHTED_FILTER_SUPPORTED /* DEPRECATED */
wester committed
1551
PNG_FP_EXPORT(68, void, png_set_filter_heuristics, (png_structp png_ptr,
wester committed
1552 1553 1554
    int heuristic_method, int num_weights, png_const_doublep filter_weights,
    png_const_doublep filter_costs))
PNG_FIXED_EXPORT(209, void, png_set_filter_heuristics_fixed,
wester committed
1555 1556 1557 1558
    (png_structp png_ptr,
    int heuristic_method, int num_weights, png_const_fixed_point_p
    filter_weights, png_const_fixed_point_p filter_costs))
#endif /*  PNG_WRITE_WEIGHTED_FILTER_SUPPORTED */
wester committed
1559 1560 1561 1562 1563 1564 1565

/* The following are no longer used and will be removed from libpng-1.7: */
#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 */

wester committed
1566
#ifdef PNG_WRITE_SUPPORTED
wester committed
1567 1568 1569 1570 1571 1572 1573 1574
/* 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
 * for PNG images, and do considerably fewer caclulations.  In the future,
 * these values may not correspond directly to the zlib compression levels.
 */
#ifdef PNG_WRITE_CUSTOMIZE_COMPRESSION_SUPPORTED
wester committed
1575 1576
PNG_EXPORT(69, void, png_set_compression_level,
    (png_structp png_ptr, int level));
wester committed
1577

wester committed
1578
PNG_EXPORT(70, void, png_set_compression_mem_level, (png_structp png_ptr,
wester committed
1579 1580
    int mem_level));

wester committed
1581
PNG_EXPORT(71, void, png_set_compression_strategy, (png_structp png_ptr,
wester committed
1582 1583 1584 1585 1586
    int strategy));

/* If PNG_WRITE_OPTIMIZE_CMF_SUPPORTED is defined, libpng will use a
 * smaller value of window_bits if it can do so safely.
 */
wester committed
1587
PNG_EXPORT(72, void, png_set_compression_window_bits, (png_structp png_ptr,
wester committed
1588 1589
    int window_bits));

wester committed
1590
PNG_EXPORT(73, void, png_set_compression_method, (png_structp png_ptr,
wester committed
1591 1592 1593 1594 1595
    int method));
#endif /* WRITE_CUSTOMIZE_COMPRESSION */

#ifdef PNG_WRITE_CUSTOMIZE_ZTXT_COMPRESSION_SUPPORTED
/* Also set zlib parameters for compressing non-IDAT chunks */
wester committed
1596 1597
PNG_EXPORT(222, void, png_set_text_compression_level,
    (png_structp png_ptr, int level));
wester committed
1598

wester committed
1599
PNG_EXPORT(223, void, png_set_text_compression_mem_level, (png_structp png_ptr,
wester committed
1600 1601
    int mem_level));

wester committed
1602
PNG_EXPORT(224, void, png_set_text_compression_strategy, (png_structp png_ptr,
wester committed
1603 1604 1605 1606 1607
    int strategy));

/* If PNG_WRITE_OPTIMIZE_CMF_SUPPORTED is defined, libpng will use a
 * smaller value of window_bits if it can do so safely.
 */
wester committed
1608 1609
PNG_EXPORT(225, void, png_set_text_compression_window_bits, (png_structp
    png_ptr, int window_bits));
wester committed
1610

wester committed
1611
PNG_EXPORT(226, void, png_set_text_compression_method, (png_structp png_ptr,
wester committed
1612
    int method));
wester committed
1613
#endif /* PNG_WRITE_CUSTOMIZE_ZTXT_COMPRESSION_SUPPORTED */
wester committed
1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626
#endif /* WRITE */

/* These next functions are called for input/output, memory, and error
 * handling.  They are in the file pngrio.c, pngwio.c, and pngerror.c,
 * 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
 * different manner by calling png_set_???_fn().  See libpng-manual.txt for
 * more information.
 */

#ifdef PNG_STDIO_SUPPORTED
/* Initialize the input/output for the PNG file to the default functions. */
wester committed
1627
PNG_EXPORT(74, void, png_init_io, (png_structp png_ptr, png_FILE_p fp));
wester committed
1628 1629 1630 1631 1632 1633 1634 1635 1636 1637
#endif

/* Replace the (error and abort), and warning functions with user
 * 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.
 */

wester committed
1638 1639 1640
PNG_EXPORT(75, void, png_set_error_fn,
    (png_structp png_ptr, png_voidp error_ptr,
    png_error_ptr error_fn, png_error_ptr warning_fn));
wester committed
1641 1642

/* Return the user pointer associated with the error functions */
wester committed
1643
PNG_EXPORT(76, png_voidp, png_get_error_ptr, (png_const_structp png_ptr));
wester committed
1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654

/* Replace the default data output functions with a user supplied one(s).
 * 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).
 * 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.
 */
wester committed
1655
PNG_EXPORT(77, void, png_set_write_fn, (png_structp png_ptr, png_voidp io_ptr,
wester committed
1656 1657 1658
    png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn));

/* Replace the default data input function with a user supplied one. */
wester committed
1659
PNG_EXPORT(78, void, png_set_read_fn, (png_structp png_ptr, png_voidp io_ptr,
wester committed
1660 1661 1662
    png_rw_ptr read_data_fn));

/* Return the user pointer associated with the I/O functions */
wester committed
1663
PNG_EXPORT(79, png_voidp, png_get_io_ptr, (png_structp png_ptr));
wester committed
1664

wester committed
1665
PNG_EXPORT(80, void, png_set_read_status_fn, (png_structp png_ptr,
wester committed
1666 1667
    png_read_status_ptr read_row_fn));

wester committed
1668
PNG_EXPORT(81, void, png_set_write_status_fn, (png_structp png_ptr,
wester committed
1669 1670 1671 1672
    png_write_status_ptr write_row_fn));

#ifdef PNG_USER_MEM_SUPPORTED
/* Replace the default memory allocation functions with user supplied one(s). */
wester committed
1673
PNG_EXPORT(82, void, png_set_mem_fn, (png_structp png_ptr, png_voidp mem_ptr,
wester committed
1674 1675
    png_malloc_ptr malloc_fn, png_free_ptr free_fn));
/* Return the user pointer associated with the memory functions */
wester committed
1676
PNG_EXPORT(83, png_voidp, png_get_mem_ptr, (png_const_structp png_ptr));
wester committed
1677 1678 1679
#endif

#ifdef PNG_READ_USER_TRANSFORM_SUPPORTED
wester committed
1680
PNG_EXPORT(84, void, png_set_read_user_transform_fn, (png_structp png_ptr,
wester committed
1681 1682 1683 1684
    png_user_transform_ptr read_user_transform_fn));
#endif

#ifdef PNG_WRITE_USER_TRANSFORM_SUPPORTED
wester committed
1685
PNG_EXPORT(85, void, png_set_write_user_transform_fn, (png_structp png_ptr,
wester committed
1686 1687 1688 1689
    png_user_transform_ptr write_user_transform_fn));
#endif

#ifdef PNG_USER_TRANSFORM_PTR_SUPPORTED
wester committed
1690
PNG_EXPORT(86, void, png_set_user_transform_info, (png_structp png_ptr,
wester committed
1691 1692 1693 1694
    png_voidp user_transform_ptr, int user_transform_depth,
    int user_transform_channels));
/* Return the user pointer associated with the user transform functions */
PNG_EXPORT(87, png_voidp, png_get_user_transform_ptr,
wester committed
1695
    (png_const_structp png_ptr));
wester committed
1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709
#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
 * 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.)
 */
wester committed
1710 1711
PNG_EXPORT(217, png_uint_32, png_get_current_row_number, (png_const_structp));
PNG_EXPORT(218, png_byte, png_get_current_pass_number, (png_const_structp));
wester committed
1712 1713 1714
#endif

#ifdef PNG_USER_CHUNKS_SUPPORTED
wester committed
1715 1716 1717
PNG_EXPORT(88, void, png_set_read_user_chunk_fn, (png_structp png_ptr,
    png_voidp user_chunk_ptr, png_user_chunk_ptr read_user_chunk_fn));
PNG_EXPORT(89, png_voidp, png_get_user_chunk_ptr, (png_const_structp png_ptr));
wester committed
1718 1719 1720 1721 1722 1723
#endif

#ifdef PNG_PROGRESSIVE_READ_SUPPORTED
/* Sets the function callbacks for the push reader, and a pointer to a
 * user-defined structure available to the callback functions.
 */
wester committed
1724
PNG_EXPORT(90, void, png_set_progressive_read_fn, (png_structp png_ptr,
wester committed
1725 1726 1727 1728
    png_voidp progressive_ptr, png_progressive_info_ptr info_fn,
    png_progressive_row_ptr row_fn, png_progressive_end_ptr end_fn));

/* Returns the user pointer associated with the push read functions */
wester committed
1729
PNG_EXPORT(91, png_voidp, png_get_progressive_ptr, (png_const_structp png_ptr));
wester committed
1730 1731

/* Function to be called when data becomes available */
wester committed
1732 1733 1734
PNG_EXPORT(92, void, png_process_data,
    (png_structp png_ptr, png_infop info_ptr,
    png_bytep buffer, png_size_t buffer_size));
wester committed
1735 1736 1737 1738 1739 1740 1741 1742

/* 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.
 */
wester committed
1743
PNG_EXPORT(219, png_size_t, png_process_data_pause, (png_structp, int save));
wester committed
1744 1745 1746 1747 1748 1749 1750

/* 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.
 */
wester committed
1751
PNG_EXPORT(220, png_uint_32, png_process_data_skip, (png_structp));
wester committed
1752

wester committed
1753
#ifdef PNG_READ_INTERLACING_SUPPORTED
wester committed
1754 1755 1756 1757 1758
/* 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.
 */
wester committed
1759
PNG_EXPORT(93, void, png_progressive_combine_row, (png_structp png_ptr,
wester committed
1760
    png_bytep old_row, png_const_bytep new_row));
wester committed
1761 1762
#endif /* PNG_READ_INTERLACING_SUPPORTED */
#endif /* PNG_PROGRESSIVE_READ_SUPPORTED */
wester committed
1763

wester committed
1764 1765 1766
PNG_EXPORTA(94, png_voidp, png_malloc,
    (png_structp png_ptr, png_alloc_size_t size),
    PNG_ALLOCATED);
wester committed
1767
/* Added at libpng version 1.4.0 */
wester committed
1768 1769 1770
PNG_EXPORTA(95, png_voidp, png_calloc,
    (png_structp png_ptr, png_alloc_size_t size),
    PNG_ALLOCATED);
wester committed
1771 1772

/* Added at libpng version 1.2.4 */
wester committed
1773
PNG_EXPORTA(96, png_voidp, png_malloc_warn, (png_structp png_ptr,
wester committed
1774 1775 1776
    png_alloc_size_t size), PNG_ALLOCATED);

/* Frees a pointer allocated by png_malloc() */
wester committed
1777
PNG_EXPORT(97, void, png_free, (png_structp png_ptr, png_voidp ptr));
wester committed
1778 1779

/* Free data that was allocated internally */
wester committed
1780 1781
PNG_EXPORT(98, void, png_free_data,
    (png_structp png_ptr, png_infop info_ptr, png_uint_32 free_me, int num));
wester committed
1782 1783

/* Reassign responsibility for freeing existing data, whether allocated
wester committed
1784 1785 1786
 * by libpng or by the application */
PNG_EXPORT(99, void, png_data_freer,
    (png_structp png_ptr, png_infop info_ptr, int freer, png_uint_32 mask));
wester committed
1787 1788 1789 1790 1791 1792

/* Assignments for png_data_freer */
#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 */
a  
Kai Westerkamp committed
1793 1794 1795 1796 1797 1798
#define PNG_FREE_HIST 0x0008
#define PNG_FREE_ICCP 0x0010
#define PNG_FREE_SPLT 0x0020
#define PNG_FREE_ROWS 0x0040
#define PNG_FREE_PCAL 0x0080
#define PNG_FREE_SCAL 0x0100
wester committed
1799 1800
#define PNG_FREE_UNKN 0x0200
#define PNG_FREE_LIST 0x0400
a  
Kai Westerkamp committed
1801 1802 1803 1804 1805
#define PNG_FREE_PLTE 0x1000
#define PNG_FREE_TRNS 0x2000
#define PNG_FREE_TEXT 0x4000
#define PNG_FREE_ALL  0x7fff
#define PNG_FREE_MUL  0x4220 /* PNG_FREE_SPLT|PNG_FREE_TEXT|PNG_FREE_UNKN */
wester committed
1806 1807

#ifdef PNG_USER_MEM_SUPPORTED
wester committed
1808 1809 1810
PNG_EXPORTA(100, png_voidp, png_malloc_default, (png_structp png_ptr,
    png_alloc_size_t size), PNG_ALLOCATED);
PNG_EXPORT(101, void, png_free_default, (png_structp png_ptr, png_voidp ptr));
wester committed
1811 1812 1813 1814
#endif

#ifdef PNG_ERROR_TEXT_SUPPORTED
/* Fatal error in PNG image of libpng - can't continue */
wester committed
1815 1816 1817
PNG_EXPORTA(102, void, png_error,
    (png_structp png_ptr, png_const_charp error_message),
    PNG_NORETURN);
wester committed
1818 1819

/* The same, but the chunk name is prepended to the error string. */
wester committed
1820
PNG_EXPORTA(103, void, png_chunk_error, (png_structp png_ptr,
wester committed
1821 1822 1823 1824
    png_const_charp error_message), PNG_NORETURN);

#else
/* Fatal error in PNG image of libpng - can't continue */
wester committed
1825
PNG_EXPORTA(104, void, png_err, (png_structp png_ptr), PNG_NORETURN);
wester committed
1826 1827 1828 1829 1830 1831
#  define png_error(s1,s2) png_err(s1)
#  define png_chunk_error(s1,s2) png_err(s1)
#endif

#ifdef PNG_WARNINGS_SUPPORTED
/* Non-fatal error in libpng.  Can continue, but may have a problem. */
wester committed
1832
PNG_EXPORT(105, void, png_warning, (png_structp png_ptr,
wester committed
1833 1834 1835
    png_const_charp warning_message));

/* Non-fatal error in libpng, chunk name is prepended to message. */
wester committed
1836
PNG_EXPORT(106, void, png_chunk_warning, (png_structp png_ptr,
wester committed
1837 1838 1839 1840 1841 1842 1843 1844 1845
    png_const_charp warning_message));
#else
#  define png_warning(s1,s2) ((void)(s1))
#  define png_chunk_warning(s1,s2) ((void)(s1))
#endif

#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. */
wester committed
1846 1847
#  undef png_benign_error
PNG_EXPORT(107, void, png_benign_error, (png_structp png_ptr,
wester committed
1848 1849
    png_const_charp warning_message));

wester committed
1850 1851 1852
/* Same, chunk name is prepended to message. */
#  undef png_chunk_benign_error
PNG_EXPORT(108, void, png_chunk_benign_error, (png_structp png_ptr,
wester committed
1853 1854 1855
    png_const_charp warning_message));

PNG_EXPORT(109, void, png_set_benign_errors,
wester committed
1856
    (png_structp png_ptr, int allowed));
wester committed
1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879
#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
#endif

/* 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.
 */
/* Returns "flag" if chunk data is valid in info_ptr. */
wester committed
1880 1881 1882
PNG_EXPORT(110, png_uint_32, png_get_valid,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_uint_32 flag));
wester committed
1883 1884

/* Returns number of bytes needed to hold a transformed row. */
wester committed
1885 1886
PNG_EXPORT(111, png_size_t, png_get_rowbytes, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1887 1888 1889 1890 1891

#ifdef PNG_INFO_IMAGE_SUPPORTED
/* Returns row_pointers, which is an array of pointers to scanlines that was
 * returned from png_read_png().
 */
wester committed
1892 1893
PNG_EXPORT(112, png_bytepp, png_get_rows,
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1894 1895 1896
/* Set row_pointers, which is an array of pointers to scanlines for use
 * by png_write_png().
 */
wester committed
1897 1898
PNG_EXPORT(113, void, png_set_rows, (png_structp png_ptr,
    png_infop info_ptr, png_bytepp row_pointers));
wester committed
1899 1900 1901
#endif

/* Returns number of color channels in image. */
wester committed
1902 1903
PNG_EXPORT(114, png_byte, png_get_channels,
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1904 1905 1906

#ifdef PNG_EASY_ACCESS_SUPPORTED
/* Returns image width in pixels. */
wester committed
1907 1908
PNG_EXPORT(115, png_uint_32, png_get_image_width, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1909 1910

/* Returns image height in pixels. */
wester committed
1911 1912
PNG_EXPORT(116, png_uint_32, png_get_image_height, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1913 1914

/* Returns image bit_depth. */
wester committed
1915 1916
PNG_EXPORT(117, png_byte, png_get_bit_depth,
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1917 1918

/* Returns image color_type. */
wester committed
1919 1920
PNG_EXPORT(118, png_byte, png_get_color_type, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1921 1922

/* Returns image filter_type. */
wester committed
1923 1924
PNG_EXPORT(119, png_byte, png_get_filter_type, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1925 1926

/* Returns image interlace_type. */
wester committed
1927 1928
PNG_EXPORT(120, png_byte, png_get_interlace_type, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1929 1930

/* Returns image compression_type. */
wester committed
1931 1932
PNG_EXPORT(121, png_byte, png_get_compression_type, (png_const_structp png_ptr,
    png_const_infop info_ptr));
wester committed
1933 1934 1935

/* Returns image resolution in pixels per meter, from pHYs chunk data. */
PNG_EXPORT(122, png_uint_32, png_get_pixels_per_meter,
wester committed
1936
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1937
PNG_EXPORT(123, png_uint_32, png_get_x_pixels_per_meter,
wester committed
1938
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1939
PNG_EXPORT(124, png_uint_32, png_get_y_pixels_per_meter,
wester committed
1940
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1941 1942 1943

/* Returns pixel aspect ratio, computed from pHYs chunk data.  */
PNG_FP_EXPORT(125, float, png_get_pixel_aspect_ratio,
wester committed
1944
    (png_const_structp png_ptr, png_const_infop info_ptr))
wester committed
1945
PNG_FIXED_EXPORT(210, png_fixed_point, png_get_pixel_aspect_ratio_fixed,
wester committed
1946
    (png_const_structp png_ptr, png_const_infop info_ptr))
wester committed
1947 1948 1949

/* Returns image x, y offset in pixels or microns, from oFFs chunk data. */
PNG_EXPORT(126, png_int_32, png_get_x_offset_pixels,
wester committed
1950
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1951
PNG_EXPORT(127, png_int_32, png_get_y_offset_pixels,
wester committed
1952
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1953
PNG_EXPORT(128, png_int_32, png_get_x_offset_microns,
wester committed
1954
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1955
PNG_EXPORT(129, png_int_32, png_get_y_offset_microns,
wester committed
1956
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
1957

wester committed
1958
#endif /* PNG_EASY_ACCESS_SUPPORTED */
wester committed
1959 1960

/* Returns pointer to signature string read from PNG header */
wester committed
1961 1962
PNG_EXPORT(130, png_const_bytep, png_get_signature,
    (png_const_structp png_ptr, png_infop info_ptr));
wester committed
1963 1964

#ifdef PNG_bKGD_SUPPORTED
wester committed
1965 1966 1967
PNG_EXPORT(131, png_uint_32, png_get_bKGD,
    (png_const_structp png_ptr, png_infop info_ptr,
    png_color_16p *background));
wester committed
1968 1969 1970
#endif

#ifdef PNG_bKGD_SUPPORTED
wester committed
1971 1972
PNG_EXPORT(132, void, png_set_bKGD, (png_structp png_ptr, png_infop info_ptr,
    png_const_color_16p background));
wester committed
1973 1974 1975
#endif

#ifdef PNG_cHRM_SUPPORTED
wester committed
1976 1977
PNG_FP_EXPORT(133, png_uint_32, png_get_cHRM, (png_const_structp png_ptr,
   png_const_infop info_ptr, double *white_x, double *white_y, double *red_x,
wester committed
1978 1979
    double *red_y, double *green_x, double *green_y, double *blue_x,
    double *blue_y))
wester committed
1980 1981
PNG_FP_EXPORT(230, png_uint_32, png_get_cHRM_XYZ, (png_structp png_ptr,
    png_const_infop info_ptr, double *red_X, double *red_Y, double *red_Z,
wester committed
1982 1983
    double *green_X, double *green_Y, double *green_Z, double *blue_X,
    double *blue_Y, double *blue_Z))
wester committed
1984
#ifdef PNG_FIXED_POINT_SUPPORTED /* Otherwise not implemented */
wester committed
1985
PNG_FIXED_EXPORT(134, png_uint_32, png_get_cHRM_fixed,
wester committed
1986 1987 1988 1989 1990 1991 1992
    (png_const_structp png_ptr,
    png_const_infop info_ptr, 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, png_fixed_point *int_blue_x,
    png_fixed_point *int_blue_y))
#endif
wester committed
1993
PNG_FIXED_EXPORT(231, png_uint_32, png_get_cHRM_XYZ_fixed,
wester committed
1994
    (png_structp png_ptr, png_const_infop info_ptr,
wester committed
1995 1996 1997 1998 1999 2000 2001 2002
    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,
    png_fixed_point *int_blue_Z))
#endif

#ifdef PNG_cHRM_SUPPORTED
wester committed
2003 2004
PNG_FP_EXPORT(135, void, png_set_cHRM,
    (png_structp png_ptr, png_infop info_ptr,
wester committed
2005 2006
    double white_x, double white_y, double red_x, double red_y, double green_x,
    double green_y, double blue_x, double blue_y))
wester committed
2007 2008
PNG_FP_EXPORT(232, void, png_set_cHRM_XYZ, (png_structp png_ptr,
    png_infop info_ptr, double red_X, double red_Y, double red_Z,
wester committed
2009 2010
    double green_X, double green_Y, double green_Z, double blue_X,
    double blue_Y, double blue_Z))
wester committed
2011 2012
PNG_FIXED_EXPORT(136, void, png_set_cHRM_fixed, (png_structp png_ptr,
    png_infop info_ptr, png_fixed_point int_white_x,
wester committed
2013 2014 2015 2016
    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,
    png_fixed_point int_blue_y))
wester committed
2017 2018
PNG_FIXED_EXPORT(233, void, png_set_cHRM_XYZ_fixed, (png_structp png_ptr,
    png_infop info_ptr, png_fixed_point int_red_X, png_fixed_point int_red_Y,
wester committed
2019 2020 2021 2022 2023 2024 2025
    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,
    png_fixed_point int_blue_Z))
#endif

#ifdef PNG_gAMA_SUPPORTED
wester committed
2026 2027 2028
PNG_FP_EXPORT(137, png_uint_32, png_get_gAMA,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    double *file_gamma))
wester committed
2029
PNG_FIXED_EXPORT(138, png_uint_32, png_get_gAMA_fixed,
wester committed
2030
    (png_const_structp png_ptr, png_const_infop info_ptr,
wester committed
2031 2032 2033 2034
    png_fixed_point *int_file_gamma))
#endif

#ifdef PNG_gAMA_SUPPORTED
wester committed
2035 2036 2037 2038
PNG_FP_EXPORT(139, void, png_set_gAMA, (png_structp png_ptr,
    png_infop info_ptr, double file_gamma))
PNG_FIXED_EXPORT(140, void, png_set_gAMA_fixed, (png_structp png_ptr,
    png_infop info_ptr, png_fixed_point int_file_gamma))
wester committed
2039 2040 2041
#endif

#ifdef PNG_hIST_SUPPORTED
wester committed
2042 2043 2044
PNG_EXPORT(141, png_uint_32, png_get_hIST,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_uint_16p *hist));
wester committed
2045 2046 2047
#endif

#ifdef PNG_hIST_SUPPORTED
wester committed
2048 2049
PNG_EXPORT(142, void, png_set_hIST, (png_structp png_ptr,
    png_infop info_ptr, png_const_uint_16p hist));
wester committed
2050 2051
#endif

wester committed
2052 2053 2054 2055
PNG_EXPORT(143, png_uint_32, png_get_IHDR,
    (png_structp png_ptr, png_infop 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));
wester committed
2056

wester committed
2057 2058 2059 2060
PNG_EXPORT(144, void, png_set_IHDR,
    (png_structp png_ptr, png_infop 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));
wester committed
2061 2062

#ifdef PNG_oFFs_SUPPORTED
wester committed
2063 2064 2065
PNG_EXPORT(145, png_uint_32, png_get_oFFs,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_int_32 *offset_x, png_int_32 *offset_y, int *unit_type));
wester committed
2066 2067 2068
#endif

#ifdef PNG_oFFs_SUPPORTED
wester committed
2069 2070 2071
PNG_EXPORT(146, void, png_set_oFFs,
    (png_structp png_ptr, png_infop info_ptr,
    png_int_32 offset_x, png_int_32 offset_y, int unit_type));
wester committed
2072 2073 2074
#endif

#ifdef PNG_pCAL_SUPPORTED
wester committed
2075 2076 2077 2078 2079
PNG_EXPORT(147, png_uint_32, png_get_pCAL,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_charp *purpose, png_int_32 *X0, png_int_32 *X1, int *type,
    int *nparams,
    png_charp *units, png_charpp *params));
wester committed
2080 2081 2082
#endif

#ifdef PNG_pCAL_SUPPORTED
wester committed
2083 2084 2085 2086
PNG_EXPORT(148, void, png_set_pCAL, (png_structp png_ptr,
    png_infop 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));
wester committed
2087 2088 2089
#endif

#ifdef PNG_pHYs_SUPPORTED
wester committed
2090 2091 2092
PNG_EXPORT(149, png_uint_32, png_get_pHYs,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_uint_32 *res_x, png_uint_32 *res_y, int *unit_type));
wester committed
2093 2094 2095
#endif

#ifdef PNG_pHYs_SUPPORTED
wester committed
2096 2097 2098
PNG_EXPORT(150, void, png_set_pHYs,
    (png_structp png_ptr, png_infop info_ptr,
    png_uint_32 res_x, png_uint_32 res_y, int unit_type));
wester committed
2099 2100
#endif

wester committed
2101 2102 2103
PNG_EXPORT(151, png_uint_32, png_get_PLTE,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_colorp *palette, int *num_palette));
wester committed
2104

wester committed
2105 2106 2107
PNG_EXPORT(152, void, png_set_PLTE,
    (png_structp png_ptr, png_infop info_ptr,
    png_const_colorp palette, int num_palette));
wester committed
2108 2109

#ifdef PNG_sBIT_SUPPORTED
wester committed
2110 2111 2112
PNG_EXPORT(153, png_uint_32, png_get_sBIT,
    (png_const_structp png_ptr, png_infop info_ptr,
    png_color_8p *sig_bit));
wester committed
2113 2114 2115
#endif

#ifdef PNG_sBIT_SUPPORTED
wester committed
2116 2117
PNG_EXPORT(154, void, png_set_sBIT,
    (png_structp png_ptr, png_infop info_ptr, png_const_color_8p sig_bit));
wester committed
2118 2119 2120
#endif

#ifdef PNG_sRGB_SUPPORTED
wester committed
2121 2122
PNG_EXPORT(155, png_uint_32, png_get_sRGB, (png_const_structp png_ptr,
    png_const_infop info_ptr, int *file_srgb_intent));
wester committed
2123 2124 2125
#endif

#ifdef PNG_sRGB_SUPPORTED
wester committed
2126 2127 2128 2129
PNG_EXPORT(156, void, png_set_sRGB,
    (png_structp png_ptr, png_infop info_ptr, int srgb_intent));
PNG_EXPORT(157, void, png_set_sRGB_gAMA_and_cHRM, (png_structp png_ptr,
    png_infop info_ptr, int srgb_intent));
wester committed
2130 2131 2132
#endif

#ifdef PNG_iCCP_SUPPORTED
wester committed
2133 2134 2135 2136
PNG_EXPORT(158, png_uint_32, png_get_iCCP,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_charpp name, int *compression_type, png_bytepp profile,
    png_uint_32 *proflen));
wester committed
2137 2138 2139
#endif

#ifdef PNG_iCCP_SUPPORTED
wester committed
2140 2141 2142 2143
PNG_EXPORT(159, void, png_set_iCCP,
    (png_structp png_ptr, png_infop info_ptr,
    png_const_charp name, int compression_type, png_const_bytep profile,
    png_uint_32 proflen));
wester committed
2144 2145 2146
#endif

#ifdef PNG_sPLT_SUPPORTED
wester committed
2147 2148 2149
PNG_EXPORT(160, png_uint_32, png_get_sPLT,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_sPLT_tpp entries));
wester committed
2150 2151 2152
#endif

#ifdef PNG_sPLT_SUPPORTED
wester committed
2153 2154 2155
PNG_EXPORT(161, void, png_set_sPLT,
    (png_structp png_ptr, png_infop info_ptr,
    png_const_sPLT_tp entries, int nentries));
wester committed
2156 2157 2158 2159
#endif

#ifdef PNG_TEXT_SUPPORTED
/* png_get_text also returns the number of text chunks in *num_text */
wester committed
2160 2161 2162
PNG_EXPORT(162, png_uint_32, png_get_text,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    png_textp *text_ptr, int *num_text));
wester committed
2163 2164 2165 2166 2167 2168 2169 2170 2171 2172
#endif

/* Note while png_set_text() will accept a structure whose text,
 * 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.
 */

#ifdef PNG_TEXT_SUPPORTED
wester committed
2173 2174 2175
PNG_EXPORT(163, void, png_set_text,
    (png_structp png_ptr, png_infop info_ptr,
    png_const_textp text_ptr, int num_text));
wester committed
2176 2177 2178
#endif

#ifdef PNG_tIME_SUPPORTED
wester committed
2179 2180
PNG_EXPORT(164, png_uint_32, png_get_tIME,
    (png_const_structp png_ptr, png_infop info_ptr, png_timep *mod_time));
wester committed
2181 2182 2183
#endif

#ifdef PNG_tIME_SUPPORTED
wester committed
2184 2185
PNG_EXPORT(165, void, png_set_tIME,
    (png_structp png_ptr, png_infop info_ptr, png_const_timep mod_time));
wester committed
2186 2187 2188
#endif

#ifdef PNG_tRNS_SUPPORTED
wester committed
2189 2190 2191
PNG_EXPORT(166, png_uint_32, png_get_tRNS,
    (png_const_structp png_ptr, png_infop info_ptr,
    png_bytep *trans_alpha, int *num_trans, png_color_16p *trans_color));
wester committed
2192 2193 2194
#endif

#ifdef PNG_tRNS_SUPPORTED
wester committed
2195 2196 2197
PNG_EXPORT(167, void, png_set_tRNS,
    (png_structp png_ptr, png_infop info_ptr,
    png_const_bytep trans_alpha, int num_trans,
wester committed
2198 2199 2200 2201
    png_const_color_16p trans_color));
#endif

#ifdef PNG_sCAL_SUPPORTED
wester committed
2202 2203 2204 2205
PNG_FP_EXPORT(168, png_uint_32, png_get_sCAL,
    (png_const_structp png_ptr, png_const_infop info_ptr,
    int *unit, double *width, double *height))
#ifdef PNG_FLOATING_ARITHMETIC_SUPPORTED
wester committed
2206 2207 2208 2209 2210 2211
/* NOTE: this API is currently implemented using floating point arithmetic,
 * 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.
 */
PNG_FIXED_EXPORT(214, png_uint_32, png_get_sCAL_fixed,
wester committed
2212 2213 2214
    (png_structp png_ptr, png_const_infop info_ptr, int *unit,
    png_fixed_point *width,
    png_fixed_point *height))
wester committed
2215 2216
#endif
PNG_EXPORT(169, png_uint_32, png_get_sCAL_s,
wester committed
2217 2218 2219 2220 2221 2222 2223 2224
    (png_const_structp png_ptr, png_const_infop info_ptr,
    int *unit, png_charpp swidth, png_charpp sheight));

PNG_FP_EXPORT(170, void, png_set_sCAL,
    (png_structp png_ptr, png_infop info_ptr,
    int unit, double width, double height))
PNG_FIXED_EXPORT(213, void, png_set_sCAL_fixed, (png_structp png_ptr,
   png_infop info_ptr, int unit, png_fixed_point width,
wester committed
2225
   png_fixed_point height))
wester committed
2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250
PNG_EXPORT(171, void, png_set_sCAL_s,
    (png_structp png_ptr, png_infop info_ptr,
    int unit, png_const_charp swidth, png_const_charp sheight));
#endif /* PNG_sCAL_SUPPORTED */

#ifdef PNG_HANDLE_AS_UNKNOWN_SUPPORTED
/* Provide a list of chunks and how they are to be handled, if the built-in
   handling or default unknown chunk handling is not desired.  Any chunks not
   listed will be handled in the default manner.  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!
      keep = 0: PNG_HANDLE_CHUNK_AS_DEFAULT: follow default behavior
           = 1: PNG_HANDLE_CHUNK_NEVER:      do not keep
           = 2: PNG_HANDLE_CHUNK_IF_SAFE:    keep only if safe-to-copy
           = 3: PNG_HANDLE_CHUNK_ALWAYS:     keep even if unsafe-to-copy
*/
PNG_EXPORT(172, void, png_set_keep_unknown_chunks,
    (png_structp png_ptr, int keep,
    png_const_bytep chunk_list, int num_chunks));

/* The handling code is returned; the result is therefore true (non-zero) if
 * special handling is required, false for the default handling.
 */
PNG_EXPORT(173, int, png_handle_as_unknown, (png_structp png_ptr,
wester committed
2251
    png_const_bytep chunk_name));
a  
Kai Westerkamp committed
2252
#endif
wester committed
2253 2254 2255
#ifdef PNG_UNKNOWN_CHUNKS_SUPPORTED
PNG_EXPORT(174, void, png_set_unknown_chunks, (png_structp png_ptr,
    png_infop info_ptr, png_const_unknown_chunkp unknowns,
wester committed
2256 2257
    int num_unknowns));
PNG_EXPORT(175, void, png_set_unknown_chunk_location,
wester committed
2258 2259 2260
    (png_structp png_ptr, png_infop info_ptr, int chunk, int location));
PNG_EXPORT(176, int, png_get_unknown_chunks, (png_const_structp png_ptr,
    png_const_infop info_ptr, png_unknown_chunkpp entries));
wester committed
2261 2262 2263 2264 2265 2266
#endif

/* Png_free_data() will turn off the "valid" flag for anything it frees.
 * If you need to turn it off for a chunk that your application has freed,
 * you can use png_set_invalid(png_ptr, info_ptr, PNG_INFO_CHNK);
 */
wester committed
2267 2268
PNG_EXPORT(177, void, png_set_invalid,
    (png_structp png_ptr, png_infop info_ptr, int mask));
wester committed
2269 2270 2271

#ifdef PNG_INFO_IMAGE_SUPPORTED
/* The "params" pointer is currently not used and is for future expansion. */
wester committed
2272
PNG_EXPORT(178, void, png_read_png, (png_structp png_ptr, png_infop info_ptr,
wester committed
2273
    int transforms, png_voidp params));
wester committed
2274
PNG_EXPORT(179, void, png_write_png, (png_structp png_ptr, png_infop info_ptr,
wester committed
2275 2276 2277 2278
    int transforms, png_voidp params));
#endif

PNG_EXPORT(180, png_const_charp, png_get_copyright,
wester committed
2279
    (png_const_structp png_ptr));
wester committed
2280
PNG_EXPORT(181, png_const_charp, png_get_header_ver,
wester committed
2281
    (png_const_structp png_ptr));
wester committed
2282
PNG_EXPORT(182, png_const_charp, png_get_header_version,
wester committed
2283
    (png_const_structp png_ptr));
wester committed
2284
PNG_EXPORT(183, png_const_charp, png_get_libpng_ver,
wester committed
2285
    (png_const_structp png_ptr));
wester committed
2286 2287

#ifdef PNG_MNG_FEATURES_SUPPORTED
wester committed
2288
PNG_EXPORT(184, png_uint_32, png_permit_mng_features, (png_structp png_ptr,
wester committed
2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301
    png_uint_32 mng_features_permitted));
#endif

/* 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

/* Strip the prepended error numbers ("#nnn ") from error and warning
 * messages before passing them to the error or warning handler.
 */
#ifdef PNG_ERROR_NUMBERS_SUPPORTED
wester committed
2302 2303
PNG_EXPORT(185, void, png_set_strip_error_numbers,
    (png_structp png_ptr,
wester committed
2304 2305 2306 2307 2308
    png_uint_32 strip_mode));
#endif

/* Added in libpng-1.2.6 */
#ifdef PNG_SET_USER_LIMITS_SUPPORTED
wester committed
2309
PNG_EXPORT(186, void, png_set_user_limits, (png_structp png_ptr,
wester committed
2310 2311
    png_uint_32 user_width_max, png_uint_32 user_height_max));
PNG_EXPORT(187, png_uint_32, png_get_user_width_max,
wester committed
2312
    (png_const_structp png_ptr));
wester committed
2313
PNG_EXPORT(188, png_uint_32, png_get_user_height_max,
wester committed
2314
    (png_const_structp png_ptr));
wester committed
2315
/* Added in libpng-1.4.0 */
wester committed
2316
PNG_EXPORT(189, void, png_set_chunk_cache_max, (png_structp png_ptr,
wester committed
2317 2318
    png_uint_32 user_chunk_cache_max));
PNG_EXPORT(190, png_uint_32, png_get_chunk_cache_max,
wester committed
2319
    (png_const_structp png_ptr));
wester committed
2320
/* Added in libpng-1.4.1 */
wester committed
2321
PNG_EXPORT(191, void, png_set_chunk_malloc_max, (png_structp png_ptr,
wester committed
2322 2323
    png_alloc_size_t user_chunk_cache_max));
PNG_EXPORT(192, png_alloc_size_t, png_get_chunk_malloc_max,
wester committed
2324
    (png_const_structp png_ptr));
wester committed
2325 2326 2327 2328
#endif

#if defined(PNG_INCH_CONVERSIONS_SUPPORTED)
PNG_EXPORT(193, png_uint_32, png_get_pixels_per_inch,
wester committed
2329
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
2330 2331

PNG_EXPORT(194, png_uint_32, png_get_x_pixels_per_inch,
wester committed
2332
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
2333 2334

PNG_EXPORT(195, png_uint_32, png_get_y_pixels_per_inch,
wester committed
2335
    (png_const_structp png_ptr, png_const_infop info_ptr));
wester committed
2336 2337

PNG_FP_EXPORT(196, float, png_get_x_offset_inches,
wester committed
2338
    (png_const_structp png_ptr, png_const_infop info_ptr))
wester committed
2339 2340
#ifdef PNG_FIXED_POINT_SUPPORTED /* otherwise not implemented. */
PNG_FIXED_EXPORT(211, png_fixed_point, png_get_x_offset_inches_fixed,
wester committed
2341
    (png_structp png_ptr, png_const_infop info_ptr))
wester committed
2342 2343
#endif

wester committed
2344 2345
PNG_FP_EXPORT(197, float, png_get_y_offset_inches, (png_const_structp png_ptr,
    png_const_infop info_ptr))
wester committed
2346 2347
#ifdef PNG_FIXED_POINT_SUPPORTED /* otherwise not implemented. */
PNG_FIXED_EXPORT(212, png_fixed_point, png_get_y_offset_inches_fixed,
wester committed
2348
    (png_structp png_ptr, png_const_infop info_ptr))
wester committed
2349 2350 2351
#endif

#  ifdef PNG_pHYs_SUPPORTED
wester committed
2352 2353
PNG_EXPORT(198, png_uint_32, png_get_pHYs_dpi, (png_const_structp png_ptr,
    png_const_infop info_ptr, png_uint_32 *res_x, png_uint_32 *res_y,
wester committed
2354
    int *unit_type));
wester committed
2355 2356
#  endif /* PNG_pHYs_SUPPORTED */
#endif  /* PNG_INCH_CONVERSIONS_SUPPORTED */
wester committed
2357 2358 2359

/* Added in libpng-1.4.0 */
#ifdef PNG_IO_STATE_SUPPORTED
wester committed
2360
PNG_EXPORT(199, png_uint_32, png_get_io_state, (png_structp png_ptr));
wester committed
2361

wester committed
2362 2363
PNG_EXPORTA(200, png_const_bytep, png_get_io_chunk_name,
    (png_structp png_ptr), PNG_DEPRECATED);
wester committed
2364
PNG_EXPORT(216, png_uint_32, png_get_io_chunk_type,
wester committed
2365
    (png_const_structp png_ptr));
wester committed
2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376

/* The flags returned by png_get_io_state() are the following: */
#  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 */
wester committed
2377
#endif /* ?PNG_IO_STATE_SUPPORTED */
wester committed
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 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420

/* 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.
 */
#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))

/* 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))

/* 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:
 */
wester committed
2421 2422 2423 2424
#define PNG_ROW_FROM_PASS_ROW(yIn, pass) \
   (((yIn)<<PNG_PASS_ROW_SHIFT(pass))+PNG_PASS_START_ROW(pass))
#define PNG_COL_FROM_PASS_COL(xIn, pass) \
   (((xIn)<<PNG_PASS_COL_SHIFT(pass))+PNG_PASS_START_COL(pass))
wester committed
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

/* 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) ( \
   ((0x110145AF>>(((7-(off))-(pass))<<2)) & 0xF) | \
   ((0x01145AF0>>(((7-(off))-(pass))<<2)) & 0xF0))

#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)

#ifdef PNG_READ_COMPOSITE_NODIV_SUPPORTED
/* 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
 * 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. :-) ]
 */

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

a  
Kai Westerkamp committed
2456 2457 2458 2459 2460
#  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          \
           - (png_uint_16)(alpha)) + 128);                \
wester committed
2461
       (composite) = (png_byte)((temp + (temp >> 8)) >> 8); }
a  
Kai Westerkamp committed
2462 2463 2464 2465 2466 2467

#  define png_composite_16(composite, fg, alpha, bg)       \
     { png_uint_32 temp = (png_uint_32)((png_uint_32)(fg)  \
           * (png_uint_32)(alpha)                          \
           + (png_uint_32)(bg)*(65535                      \
           - (png_uint_32)(alpha)) + 32768);               \
wester committed
2468
       (composite) = (png_uint_16)((temp + (temp >> 16)) >> 16); }
wester committed
2469 2470 2471

#else  /* Standard method using integer division */

wester committed
2472 2473 2474 2475
#  define png_composite(composite, fg, alpha, bg)                          \
     (composite) = (png_byte)(((png_uint_16)(fg) * (png_uint_16)(alpha) +  \
     (png_uint_16)(bg) * (png_uint_16)(255 - (png_uint_16)(alpha)) +       \
     127) / 255)
a  
Kai Westerkamp committed
2476 2477

#  define png_composite_16(composite, fg, alpha, bg)                         \
wester committed
2478 2479 2480 2481
     (composite) = (png_uint_16)(((png_uint_32)(fg) * (png_uint_32)(alpha) + \
     (png_uint_32)(bg)*(png_uint_32)(65535 - (png_uint_32)(alpha)) +         \
     32767) / 65535)
#endif /* PNG_READ_COMPOSITE_NODIV_SUPPORTED */
wester committed
2482 2483 2484 2485 2486 2487 2488

#ifdef PNG_READ_INT_FUNCTIONS_SUPPORTED
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));
#endif

wester committed
2489
PNG_EXPORT(204, png_uint_32, png_get_uint_31, (png_structp png_ptr,
wester committed
2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514
    png_const_bytep buf));
/* No png_get_int_16 -- may be added if there's a real need for it. */

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

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

#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.
 */
wester committed
2515
#  define png_get_uint_32(buf) \
a  
Kai Westerkamp committed
2516 2517 2518 2519
     (((png_uint_32)(*(buf)) << 24) + \
      ((png_uint_32)(*((buf) + 1)) << 16) + \
      ((png_uint_32)(*((buf) + 2)) << 8) + \
      ((png_uint_32)(*((buf) + 3))))
wester committed
2520 2521 2522 2523

   /* 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.
    */
wester committed
2524
#  define png_get_uint_16(buf) \
a  
Kai Westerkamp committed
2525 2526 2527
     ((png_uint_16) \
      (((unsigned int)(*(buf)) << 8) + \
       ((unsigned int)(*((buf) + 1)))))
wester committed
2528

wester committed
2529
#  define png_get_int_32(buf) \
a  
Kai Westerkamp committed
2530 2531 2532
     ((png_int_32)((*(buf) & 0x80) \
      ? -((png_int_32)(((png_get_uint_32(buf)^0xffffffffU)+1U)&0x7fffffffU)) \
      : (png_int_32)png_get_uint_32(buf)))
wester committed
2533 2534 2535
#endif

#ifdef PNG_CHECK_FOR_INVALID_INDEX_SUPPORTED
wester committed
2536 2537
PNG_EXPORT(234, void, png_set_check_for_invalid_index, (png_structp png_ptr,
    int allowed));
wester committed
2538
#  ifdef PNG_GET_PALETTE_MAX_SUPPORTED
wester committed
2539
PNG_EXPORT(235, int, png_get_palette_max, (png_const_structp png_ptr,
wester committed
2540 2541 2542 2543 2544
    png_const_infop info_ptr));
#  endif
#endif /* CHECK_FOR_INVALID_INDEX */

/*******************************************************************************
wester committed
2545
 *  IMPLEMENTATION OPTIONS
wester committed
2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568
 *******************************************************************************
 *
 * 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
wester committed
2569
#define PNG_OPTION_NEXT  2 /* Next option - numbers must be even */
wester committed
2570 2571 2572 2573 2574 2575 2576

/* 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

wester committed
2577
PNG_EXPORT(236, int, png_set_option, (png_structp png_ptr, int option,
wester committed
2578
   int onoff));
wester committed
2579
#endif
wester committed
2580 2581

/*******************************************************************************
wester committed
2582
 *  END OF HARDWARE OPTIONS
wester committed
2583 2584
 ******************************************************************************/

wester committed
2585 2586
/* Maintainer: Put new public prototypes here ^, in libpng.3, and project
 * defs
wester committed
2587 2588 2589
 */

/* The last ordinal number (this is the *last* one already used; the next
wester committed
2590 2591
 * one to use is one more than this.)  Maintainer, remember to add an entry to
 * scripts/symbols.def as well.
wester committed
2592 2593
 */
#ifdef PNG_EXPORT_LAST_ORDINAL
wester committed
2594
  PNG_EXPORT_LAST_ORDINAL(236);
wester committed
2595 2596 2597 2598 2599 2600 2601 2602 2603
#endif

#ifdef __cplusplus
}
#endif

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