PageRenderTime 51ms CodeModel.GetById 19ms app.highlight 9ms RepoModel.GetById 1ms app.codeStats 1ms

/src/FreeImage/Source/LibPNG/libpng-manual.txt

https://bitbucket.org/cabalistic/ogredeps/
Plain Text | 4628 lines | 3570 code | 1058 blank | 0 comment | 0 complexity | 701b19a436624e206255c9cb8c4169b1 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1libpng-manual.txt - A description on how to use and modify libpng
   2
   3 libpng version 1.5.9 - February 18, 2012
   4 Updated and distributed by Glenn Randers-Pehrson
   5 <glennrp at users.sourceforge.net>
   6 Copyright (c) 1998-2011 Glenn Randers-Pehrson
   7
   8 This document is released under the libpng license.
   9 For conditions of distribution and use, see the disclaimer
  10 and license in png.h
  11
  12 Based on:
  13
  14 libpng versions 0.97, January 1998, through 1.5.9 - February 18, 2012
  15 Updated and distributed by Glenn Randers-Pehrson
  16 Copyright (c) 1998-2011 Glenn Randers-Pehrson
  17
  18 libpng 1.0 beta 6  version 0.96 May 28, 1997
  19 Updated and distributed by Andreas Dilger
  20 Copyright (c) 1996, 1997 Andreas Dilger
  21
  22 libpng 1.0 beta 2 - version 0.88  January 26, 1996
  23 For conditions of distribution and use, see copyright
  24 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
  25 Schalnat, Group 42, Inc.
  26
  27 Updated/rewritten per request in the libpng FAQ
  28 Copyright (c) 1995, 1996 Frank J. T. Wojcik
  29 December 18, 1995 & January 20, 1996
  30
  31I. Introduction
  32
  33This file describes how to use and modify the PNG reference library
  34(known as libpng) for your own use.  There are five sections to this
  35file: introduction, structures, reading, writing, and modification and
  36configuration notes for various special platforms.  In addition to this
  37file, example.c is a good starting point for using the library, as
  38it is heavily commented and should include everything most people
  39will need.  We assume that libpng is already installed; see the
  40INSTALL file for instructions on how to install libpng.
  41
  42For examples of libpng usage, see the files "example.c", "pngtest.c",
  43and the files in the "contrib" directory, all of which are included in
  44the libpng distribution.
  45
  46Libpng was written as a companion to the PNG specification, as a way
  47of reducing the amount of time and effort it takes to support the PNG
  48file format in application programs.
  49
  50The PNG specification (second edition), November 2003, is available as
  51a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
  52<http://www.w3.org/TR/2003/REC-PNG-20031110/
  53The W3C and ISO documents have identical technical content.
  54
  55The PNG-1.2 specification is available at
  56<http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
  57to the PNG specification (second edition) but has some additional material.
  58
  59The PNG-1.0 specification is available
  60as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
  61W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
  62
  63Some additional chunks are described in the special-purpose public chunks
  64documents at <http://www.libpng.org/pub/png/documents/>.
  65
  66Other information
  67about PNG, and the latest version of libpng, can be found at the PNG home
  68page, <http://www.libpng.org/pub/png/>.
  69
  70Most users will not have to modify the library significantly; advanced
  71users may want to modify it more.  All attempts were made to make it as
  72complete as possible, while keeping the code easy to understand.
  73Currently, this library only supports C.  Support for other languages
  74is being considered.
  75
  76Libpng has been designed to handle multiple sessions at one time,
  77to be easily modifiable, to be portable to the vast majority of
  78machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
  79to use.  The ultimate goal of libpng is to promote the acceptance of
  80the PNG file format in whatever way possible.  While there is still
  81work to be done (see the TODO file), libpng should cover the
  82majority of the needs of its users.
  83
  84Libpng uses zlib for its compression and decompression of PNG files.
  85Further information about zlib, and the latest version of zlib, can
  86be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
  87The zlib compression utility is a general purpose utility that is
  88useful for more than PNG files, and can be used without libpng.
  89See the documentation delivered with zlib for more details.
  90You can usually find the source files for the zlib utility wherever you
  91find the libpng source files.
  92
  93Libpng is thread safe, provided the threads are using different
  94instances of the structures.  Each thread should have its own
  95png_struct and png_info instances, and thus its own image.
  96Libpng does not protect itself against two threads using the
  97same instance of a structure.
  98
  99II. Structures
 100
 101There are two main structures that are important to libpng, png_struct
 102and png_info.  Both are internal structures that are no longer exposed
 103in the libpng interface (as of libpng 1.5.0).
 104
 105The png_info structure is designed to provide information about the
 106PNG file.  At one time, the fields of png_info were intended to be
 107directly accessible to the user.  However, this tended to cause problems
 108with applications using dynamically loaded libraries, and as a result
 109a set of interface functions for png_info (the png_get_*() and png_set_*()
 110functions) was developed, and direct access to the png_info fields was
 111deprecated..
 112
 113The png_struct structure is the object used by the library to decode a
 114single image.  As of 1.5.0 this structure is also not exposed.
 115
 116Almost all libpng APIs require a pointer to a png_struct as the first argument.
 117Many (in particular the png_set and png_get APIs) also require a pointer
 118to png_info as the second argument.  Some application visible macros
 119defined in png.h designed for basic data access (reading and writing
 120integers in the PNG format) don't take a png_info pointer, but it's almost
 121always safe to assume that a (png_struct*) has to be passed to call an API
 122function.
 123
 124You can have more than one png_info structure associated with an image,
 125as illustrated in pngtest.c, one for information valid prior to the
 126IDAT chunks and another (called "end_info" below) for things after them.
 127
 128The png.h header file is an invaluable reference for programming with libpng.
 129And while I'm on the topic, make sure you include the libpng header file:
 130
 131#include <png.h>
 132
 133and also (as of libpng-1.5.0) the zlib header file, if you need it:
 134
 135#include <zlib.h>
 136
 137Types
 138
 139The png.h header file defines a number of integral types used by the
 140APIs.  Most of these are fairly obvious; for example types corresponding
 141to integers of particular sizes and types for passing color values.
 142
 143One exception is how non-integral numbers are handled.  For application
 144convenience most APIs that take such numbers have C (double) arguments,
 145however internally PNG, and libpng, use 32 bit signed integers and encode
 146the value by multiplying by 100,000.  As of libpng 1.5.0 a convenience
 147macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
 148which is simply (png_int_32).
 149
 150All APIs that take (double) arguments also have a matching API that
 151takes the corresponding fixed point integer arguments.  The fixed point
 152API has the same name as the floating point one with "_fixed" appended.
 153The actual range of values permitted in the APIs is frequently less than
 154the full range of (png_fixed_point) (-21474 to +21474).  When APIs require
 155a non-negative argument the type is recorded as png_uint_32 above.  Consult
 156the header file and the text below for more information.
 157
 158Special care must be take with sCAL chunk handling because the chunk itself
 159uses non-integral values encoded as strings containing decimal floating point
 160numbers.  See the comments in the header file.
 161
 162Configuration
 163
 164The main header file function declarations are frequently protected by C
 165preprocessing directives of the form:
 166
 167    #ifdef PNG_feature_SUPPORTED
 168    declare-function
 169    #endif
 170    ...
 171    #ifdef PNG_feature_SUPPORTED
 172    use-function
 173    #endif
 174
 175The library can be built without support for these APIs, although a
 176standard build will have all implemented APIs.  Application programs
 177should check the feature macros before using an API for maximum
 178portability.  From libpng 1.5.0 the feature macros set during the build
 179of libpng are recorded in the header file "pnglibconf.h" and this file
 180is always included by png.h.
 181
 182If you don't need to change the library configuration from the default, skip to
 183the next section ("Reading").
 184
 185Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
 186of the build project files in the 'projects' directory simply copy
 187scripts/pnglibconf.h.prebuilt to pnglibconf.h.  This means that these build
 188systems do not permit easy auto-configuration of the library - they only
 189support the default configuration.
 190
 191The easiest way to make minor changes to the libpng configuration when
 192auto-configuration is supported is to add definitions to the command line
 193using (typically) CPPFLAGS.  For example:
 194
 195CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
 196
 197will change the internal libpng math implementation for gamma correction and
 198other arithmetic calculations to fixed point, avoiding the need for fast
 199floating point support.  The result can be seen in the generated pnglibconf.h -
 200make sure it contains the changed feature macro setting.
 201
 202If you need to make more extensive configuration changes - more than one or two
 203feature macro settings - you can either add -DPNG_USER_CONFIG to the build
 204command line and put a list of feature macro settings in pngusr.h or you can set
 205DFA_XTRA (a makefile variable) to a file containing the same information in the
 206form of 'option' settings.
 207
 208A. Changing pnglibconf.h
 209
 210A variety of methods exist to build libpng.  Not all of these support
 211reconfiguration of pnglibconf.h.  To reconfigure pnglibconf.h it must either be
 212rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
 213
 214Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
 215pnglibconf.h and changing the lines defining the supported features, paying
 216very close attention to the 'option' information in scripts/pnglibconf.dfa
 217that describes those features and their requirements.  This is easy to get
 218wrong.
 219
 220B. Configuration using DFA_XTRA
 221
 222Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
 223variant such as 'nawk' or 'gawk', is available.  The configure build will
 224automatically find an appropriate awk and build pnglibconf.h.
 225The scripts/pnglibconf.mak file contains a set of make rules for doing the
 226same thing if configure is not used, and many of the makefiles in the scripts
 227directory use this approach.
 228
 229When rebuilding simply write a new file containing changed options and set
 230DFA_XTRA to the name of this file.  This causes the build to append the new file
 231to the end of scripts/pnglibconf.dfa.  The pngusr.dfa file should contain lines
 232of the following forms:
 233
 234everything = off
 235
 236This turns all optional features off.  Include it at the start of pngusr.dfa to
 237make it easier to build a minimal configuration.  You will need to turn at least
 238some features on afterward to enable either reading or writing code, or both.
 239
 240option feature on
 241option feature off
 242
 243Enable or disable a single feature.  This will automatically enable other
 244features required by a feature that is turned on or disable other features that
 245require a feature which is turned off.  Conflicting settings will cause an error
 246message to be emitted by awk.
 247
 248setting feature default value
 249
 250Changes the default value of setting 'feature' to 'value'.  There are a small
 251number of settings listed at the top of pnglibconf.h, they are documented in the
 252source code.  Most of these values have performance implications for the library
 253but most of them have no visible effect on the API.  Some can also be overridden
 254from the API.
 255
 256This method of building a customized pnglibconf.h is illustrated in
 257contrib/pngminim/*.  See the "$(PNGCONF):" target in the makefile and
 258pngusr.dfa in these directories.
 259
 260C. Configuration using PNG_USR_CONFIG
 261
 262If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
 263pngusr.h will automatically be included before the options in
 264scripts/pnglibconf.dfa are processed.  Your pngusr.h file should contain only
 265macro definitions turning features on or off or setting settings.
 266
 267Apart from the global setting "everything = off" all the options listed above
 268can be set using macros in pngusr.h:
 269
 270#define PNG_feature_SUPPORTED
 271
 272is equivalent to:
 273
 274option feature on
 275
 276#define PNG_NO_feature
 277
 278is equivalent to:
 279
 280option feature off
 281
 282#define PNG_feature value
 283
 284is equivalent to:
 285
 286setting feature default value
 287
 288Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
 289pngusr file you supply override the contents of scripts/pnglibconf.dfa
 290
 291If confusing or incomprehensible behavior results it is possible to
 292examine the intermediate file pnglibconf.dfn to find the full set of
 293dependency information for each setting and option.  Simply locate the
 294feature in the file and read the C comments that precede it.
 295
 296This method is also illustrated in the contrib/pngminim/* makefiles and
 297pngusr.h.
 298
 299III. Reading
 300
 301We'll now walk you through the possible functions to call when reading
 302in a PNG file sequentially, briefly explaining the syntax and purpose
 303of each one.  See example.c and png.h for more detail.  While
 304progressive reading is covered in the next section, you will still
 305need some of the functions discussed in this section to read a PNG
 306file.
 307
 308Setup
 309
 310You will want to do the I/O initialization(*) before you get into libpng,
 311so if it doesn't work, you don't have much to undo.  Of course, you
 312will also want to insure that you are, in fact, dealing with a PNG
 313file.  Libpng provides a simple check to see if a file is a PNG file.
 314To use it, pass in the first 1 to 8 bytes of the file to the function
 315png_sig_cmp(), and it will return 0 (false) if the bytes match the
 316corresponding bytes of the PNG signature, or nonzero (true) otherwise.
 317Of course, the more bytes you pass in, the greater the accuracy of the
 318prediction.
 319
 320If you are intending to keep the file pointer open for use in libpng,
 321you must ensure you don't read more than 8 bytes from the beginning
 322of the file, and you also have to make a call to png_set_sig_bytes_read()
 323with the number of bytes you read from the beginning.  Libpng will
 324then only check the bytes (if any) that your program didn't read.
 325
 326(*): If you are not using the standard I/O functions, you will need
 327to replace them with custom functions.  See the discussion under
 328Customizing libpng.
 329
 330
 331    FILE *fp = fopen(file_name, "rb");
 332    if (!fp)
 333    {
 334       return (ERROR);
 335    }
 336
 337    fread(header, 1, number, fp);
 338    is_png = !png_sig_cmp(header, 0, number);
 339
 340    if (!is_png)
 341    {
 342       return (NOT_PNG);
 343    }
 344
 345
 346Next, png_struct and png_info need to be allocated and initialized.  In
 347order to ensure that the size of these structures is correct even with a
 348dynamically linked libpng, there are functions to initialize and
 349allocate the structures.  We also pass the library version, optional
 350pointers to error handling functions, and a pointer to a data struct for
 351use by the error functions, if necessary (the pointer and functions can
 352be NULL if the default error handlers are to be used).  See the section
 353on Changes to Libpng below regarding the old initialization functions.
 354The structure allocation functions quietly return NULL if they fail to
 355create the structure, so your application should check for that.
 356
 357    png_structp png_ptr = png_create_read_struct
 358        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
 359        user_error_fn, user_warning_fn);
 360
 361    if (!png_ptr)
 362       return (ERROR);
 363
 364    png_infop info_ptr = png_create_info_struct(png_ptr);
 365
 366    if (!info_ptr)
 367    {
 368       png_destroy_read_struct(&png_ptr,
 369           (png_infopp)NULL, (png_infopp)NULL);
 370       return (ERROR);
 371    }
 372
 373If you want to use your own memory allocation routines,
 374use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
 375png_create_read_struct_2() instead of png_create_read_struct():
 376
 377    png_structp png_ptr = png_create_read_struct_2
 378        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
 379        user_error_fn, user_warning_fn, (png_voidp)
 380        user_mem_ptr, user_malloc_fn, user_free_fn);
 381
 382The error handling routines passed to png_create_read_struct()
 383and the memory alloc/free routines passed to png_create_struct_2()
 384are only necessary if you are not using the libpng supplied error
 385handling and memory alloc/free functions.
 386
 387When libpng encounters an error, it expects to longjmp back
 388to your routine.  Therefore, you will need to call setjmp and pass
 389your png_jmpbuf(png_ptr).  If you read the file from different
 390routines, you will need to update the longjmp buffer every time you enter
 391a new routine that will call a png_*() function.
 392
 393See your documentation of setjmp/longjmp for your compiler for more
 394information on setjmp/longjmp.  See the discussion on libpng error
 395handling in the Customizing Libpng section below for more information
 396on the libpng error handling.  If an error occurs, and libpng longjmp's
 397back to your setjmp, you will want to call png_destroy_read_struct() to
 398free any memory.
 399
 400    if (setjmp(png_jmpbuf(png_ptr)))
 401    {
 402       png_destroy_read_struct(&png_ptr, &info_ptr,
 403           &end_info);
 404       fclose(fp);
 405       return (ERROR);
 406    }
 407
 408Pass (png_infopp)NULL instead of &end_info if you didn't create
 409an end_info structure.
 410
 411If you would rather avoid the complexity of setjmp/longjmp issues,
 412you can compile libpng with PNG_NO_SETJMP, in which case
 413errors will result in a call to PNG_ABORT() which defaults to abort().
 414
 415You can #define PNG_ABORT() to a function that does something
 416more useful than abort(), as long as your function does not
 417return.
 418
 419Now you need to set up the input code.  The default for libpng is to
 420use the C function fread().  If you use this, you will need to pass a
 421valid FILE * in the function png_init_io().  Be sure that the file is
 422opened in binary mode.  If you wish to handle reading data in another
 423way, you need not call the png_init_io() function, but you must then
 424implement the libpng I/O methods discussed in the Customizing Libpng
 425section below.
 426
 427    png_init_io(png_ptr, fp);
 428
 429If you had previously opened the file and read any of the signature from
 430the beginning in order to see if this was a PNG file, you need to let
 431libpng know that there are some bytes missing from the start of the file.
 432
 433    png_set_sig_bytes(png_ptr, number);
 434
 435You can change the zlib compression buffer size to be used while
 436reading compressed data with
 437
 438    png_set_compression_buffer_size(png_ptr, buffer_size);
 439
 440where the default size is 8192 bytes.  Note that the buffer size
 441is changed immediately and the buffer is reallocated immediately,
 442instead of setting a flag to be acted upon later.
 443
 444If you want CRC errors to be handled in a different manner than
 445the default, use
 446
 447    png_set_crc_action(png_ptr, crit_action, ancil_action);
 448
 449The values for png_set_crc_action() say how libpng is to handle CRC errors in
 450ancillary and critical chunks, and whether to use the data contained
 451therein.  Note that it is impossible to "discard" data in a critical
 452chunk.
 453
 454Choices for (int) crit_action are
 455   PNG_CRC_DEFAULT      0  error/quit
 456   PNG_CRC_ERROR_QUIT   1  error/quit
 457   PNG_CRC_WARN_USE     3  warn/use data
 458   PNG_CRC_QUIET_USE    4  quiet/use data
 459   PNG_CRC_NO_CHANGE    5  use the current value
 460
 461Choices for (int) ancil_action are
 462   PNG_CRC_DEFAULT      0  error/quit
 463   PNG_CRC_ERROR_QUIT   1  error/quit
 464   PNG_CRC_WARN_DISCARD 2  warn/discard data
 465   PNG_CRC_WARN_USE     3  warn/use data
 466   PNG_CRC_QUIET_USE    4  quiet/use data
 467   PNG_CRC_NO_CHANGE    5  use the current value
 468
 469Setting up callback code
 470
 471You can set up a callback function to handle any unknown chunks in the
 472input stream. You must supply the function
 473
 474    read_chunk_callback(png_structp png_ptr,
 475         png_unknown_chunkp chunk);
 476    {
 477       /* The unknown chunk structure contains your
 478          chunk data, along with similar data for any other
 479          unknown chunks: */
 480
 481           png_byte name[5];
 482           png_byte *data;
 483           png_size_t size;
 484
 485       /* Note that libpng has already taken care of
 486          the CRC handling */
 487
 488       /* put your code here.  Search for your chunk in the
 489          unknown chunk structure, process it, and return one
 490          of the following: */
 491
 492       return (-n); /* chunk had an error */
 493       return (0); /* did not recognize */
 494       return (n); /* success */
 495    }
 496
 497(You can give your function another name that you like instead of
 498"read_chunk_callback")
 499
 500To inform libpng about your function, use
 501
 502    png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
 503        read_chunk_callback);
 504
 505This names not only the callback function, but also a user pointer that
 506you can retrieve with
 507
 508    png_get_user_chunk_ptr(png_ptr);
 509
 510If you call the png_set_read_user_chunk_fn() function, then all unknown
 511chunks will be saved when read, in case your callback function will need
 512one or more of them.  This behavior can be changed with the
 513png_set_keep_unknown_chunks() function, described below.
 514
 515At this point, you can set up a callback function that will be
 516called after each row has been read, which you can use to control
 517a progress meter or the like.  It's demonstrated in pngtest.c.
 518You must supply a function
 519
 520    void read_row_callback(png_structp png_ptr,
 521       png_uint_32 row, int pass);
 522    {
 523      /* put your code here */
 524    }
 525
 526(You can give it another name that you like instead of "read_row_callback")
 527
 528To inform libpng about your function, use
 529
 530    png_set_read_status_fn(png_ptr, read_row_callback);
 531
 532When this function is called the row has already been completely processed and
 533the 'row' and 'pass' refer to the next row to be handled.  For the
 534non-interlaced case the row that was just handled is simply one less than the
 535passed in row number, and pass will always be 0.  For the interlaced case the
 536same applies unless the row value is 0, in which case the row just handled was
 537the last one from one of the preceding passes.  Because interlacing may skip a
 538pass you cannot be sure that the preceding pass is just 'pass-1', if you really
 539need to know what the last pass is record (row,pass) from the callback and use
 540the last recorded value each time.
 541
 542As with the user transform you can find the output row using the
 543PNG_ROW_FROM_PASS_ROW macro.
 544
 545Unknown-chunk handling
 546
 547Now you get to set the way the library processes unknown chunks in the
 548input PNG stream. Both known and unknown chunks will be read.  Normal
 549behavior is that known chunks will be parsed into information in
 550various info_ptr members while unknown chunks will be discarded. This
 551behavior can be wasteful if your application will never use some known
 552chunk types. To change this, you can call:
 553
 554    png_set_keep_unknown_chunks(png_ptr, keep,
 555        chunk_list, num_chunks);
 556    keep       - 0: default unknown chunk handling
 557                 1: ignore; do not keep
 558                 2: keep only if safe-to-copy
 559                 3: keep even if unsafe-to-copy
 560
 561               You can use these definitions:
 562                 PNG_HANDLE_CHUNK_AS_DEFAULT   0
 563                 PNG_HANDLE_CHUNK_NEVER        1
 564                 PNG_HANDLE_CHUNK_IF_SAFE      2
 565                 PNG_HANDLE_CHUNK_ALWAYS       3
 566
 567    chunk_list - list of chunks affected (a byte string,
 568                 five bytes per chunk, NULL or '\0' if
 569                 num_chunks is 0)
 570
 571    num_chunks - number of chunks affected; if 0, all
 572                 unknown chunks are affected.  If nonzero,
 573                 only the chunks in the list are affected
 574
 575Unknown chunks declared in this way will be saved as raw data onto a
 576list of png_unknown_chunk structures.  If a chunk that is normally
 577known to libpng is named in the list, it will be handled as unknown,
 578according to the "keep" directive.  If a chunk is named in successive
 579instances of png_set_keep_unknown_chunks(), the final instance will
 580take precedence.  The IHDR and IEND chunks should not be named in
 581chunk_list; if they are, libpng will process them normally anyway.
 582If you know that your application will never make use of some particular
 583chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
 584
 585Here is an example of the usage of png_set_keep_unknown_chunks(),
 586where the private "vpAg" chunk will later be processed by a user chunk
 587callback function:
 588
 589    png_byte vpAg[5]={118, 112,  65, 103, (png_byte) '\0'};
 590
 591    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
 592      png_byte unused_chunks[]=
 593      {
 594        104,  73,  83,  84, (png_byte) '\0',   /* hIST */
 595        105,  84,  88, 116, (png_byte) '\0',   /* iTXt */
 596        112,  67,  65,  76, (png_byte) '\0',   /* pCAL */
 597        115,  67,  65,  76, (png_byte) '\0',   /* sCAL */
 598        115,  80,  76,  84, (png_byte) '\0',   /* sPLT */
 599        116,  73,  77,  69, (png_byte) '\0',   /* tIME */
 600      };
 601    #endif
 602
 603    ...
 604
 605    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
 606      /* ignore all unknown chunks: */
 607      png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
 608
 609      /* except for vpAg: */
 610      png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
 611
 612      /* also ignore unused known chunks: */
 613      png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
 614         (int)sizeof(unused_chunks)/5);
 615    #endif
 616
 617User limits
 618
 619The PNG specification allows the width and height of an image to be as
 620large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
 621Since very few applications really need to process such large images,
 622we have imposed an arbitrary 1-million limit on rows and columns.
 623Larger images will be rejected immediately with a png_error() call. If
 624you wish to change this limit, you can use
 625
 626   png_set_user_limits(png_ptr, width_max, height_max);
 627
 628to set your own limits, or use width_max = height_max = 0x7fffffffL
 629to allow all valid dimensions (libpng may reject some very large images
 630anyway because of potential buffer overflow conditions).
 631
 632You should put this statement after you create the PNG structure and
 633before calling png_read_info(), png_read_png(), or png_process_data().
 634
 635When writing a PNG datastream, put this statement before calling
 636png_write_info() or png_write_png().
 637
 638If you need to retrieve the limits that are being applied, use
 639
 640   width_max = png_get_user_width_max(png_ptr);
 641   height_max = png_get_user_height_max(png_ptr);
 642
 643The PNG specification sets no limit on the number of ancillary chunks
 644allowed in a PNG datastream.  You can impose a limit on the total number
 645of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
 646
 647   png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
 648
 649where 0x7fffffffL means unlimited.  You can retrieve this limit with
 650
 651   chunk_cache_max = png_get_chunk_cache_max(png_ptr);
 652
 653This limit also applies to the number of buffers that can be allocated
 654by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
 655
 656You can also set a limit on the amount of memory that a compressed chunk
 657other than IDAT can occupy, with
 658
 659   png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
 660
 661and you can retrieve the limit with
 662
 663   chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
 664
 665Any chunks that would cause either of these limits to be exceeded will
 666be ignored.
 667
 668Information about your system
 669
 670If you intend to display the PNG or to incorporate it in other image data you
 671need to tell libpng information about your display or drawing surface so that
 672libpng can convert the values in the image to match the display.
 673
 674From libpng-1.5.4 this information can be set before reading the PNG file
 675header.  In earlier versions png_set_gamma() existed but behaved incorrectly if
 676called before the PNG file header had been read and png_set_alpha_mode() did not
 677exist.
 678
 679If you need to support versions prior to libpng-1.5.4 test the version number
 680as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
 681described in the appropriate manual page.
 682
 683You give libpng the encoding expected by your system expressed as a 'gamma'
 684value.  You can also specify a default encoding for the PNG file in
 685case the required information is missing from the file.  By default libpng
 686assumes that the PNG data matches your system, to keep this default call:
 687
 688   png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
 689
 690or you can use the fixed point equivalent:
 691
 692   png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_gamma);
 693
 694If you don't know the gamma for your system it is probably 2.2 - a good
 695approximation to the IEC standard for display systems (sRGB).  If images are
 696too contrasty or washed out you got the value wrong - check your system
 697documentation!
 698
 699Many systems permit the system gamma to be changed via a lookup table in the
 700display driver, a few systems, including older Macs, change the response by
 701default.  As of 1.5.4 three special values are available to handle common
 702situations:
 703
 704   PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
 705                     standard.  This matches almost all systems.
 706   PNG_GAMMA_MAC_18: Indicates that the system is an older (pre Mac OS 10.6)
 707                     Apple Macintosh system with the default settings.
 708   PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates that the
 709                     system expects data with no gamma encoding.
 710
 711You would use the linear (unencoded) value if you need to process the pixel
 712values further because this avoids the need to decode and reencode each
 713component value whenever arithmetic is performed.  A lot of graphics software
 714uses linear values for this reason, often with higher precision component values
 715to preserve overall accuracy.
 716
 717The second thing you may need to tell libpng about is how your system handles
 718alpha channel information.  Some, but not all, PNG files contain an alpha
 719channel.  To display these files correctly you need to compose the data onto a
 720suitable background, as described in the PNG specification.
 721
 722Libpng only supports composing onto a single color (using png_set_background;
 723see below).  Otherwise you must do the composition yourself and, in this case,
 724you may need to call png_set_alpha_mode:
 725
 726#if PNG_LIBPNG_VER >= 10504
 727   png_set_alpha_mode(png_ptr, mode, screen_gamma);
 728#else
 729   png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
 730#endif
 731
 732The screen_gamma value is the same as the argument to png_set_gamma; however,
 733how it affects the output depends on the mode.  png_set_alpha_mode() sets the
 734file gamma default to 1/screen_gamma, so normally you don't need to call
 735png_set_gamma.  If you need different defaults call png_set_gamma() before
 736png_set_alpha_mode() - if you call it after it will override the settings made
 737by png_set_alpha_mode().
 738
 739The mode is as follows:
 740
 741    PNG_ALPHA_PNG: The data is encoded according to the PNG specification.  Red,
 742green and blue, or gray, components are gamma encoded color
 743values and are not premultiplied by the alpha value.  The
 744alpha value is a linear measure of the contribution of the
 745pixel to the corresponding final output pixel.
 746
 747You should normally use this format if you intend to perform
 748color correction on the color values; most, maybe all, color
 749correction software has no handling for the alpha channel and,
 750anyway, the math to handle pre-multiplied component values is
 751unnecessarily complex.
 752
 753Before you do any arithmetic on the component values you need
 754to remove the gamma encoding and multiply out the alpha
 755channel.  See the PNG specification for more detail.  It is
 756important to note that when an image with an alpha channel is
 757scaled, linear encoded, pre-multiplied component values must
 758be used!
 759
 760The remaining modes assume you don't need to do any further color correction or
 761that if you do, your color correction software knows all about alpha (it
 762probably doesn't!)
 763
 764    PNG_ALPHA_STANDARD:  The data libpng produces
 765is encoded in the standard way
 766assumed by most correctly written graphics software.
 767The gamma encoding will be removed by libpng and the
 768linear component values will be pre-multiplied by the
 769alpha channel.
 770
 771With this format the final image must be re-encoded to
 772match the display gamma before the image is displayed.
 773If your system doesn't do that, yet still seems to
 774perform arithmetic on the pixels without decoding them,
 775it is broken - check out the modes below.
 776
 777With PNG_ALPHA_STANDARD libpng always produces linear
 778component values, whatever screen_gamma you supply.  The
 779screen_gamma value is, however, used as a default for
 780the file gamma if the PNG file has no gamma information.
 781
 782If you call png_set_gamma() after png_set_alpha_mode() you
 783will override the linear encoding.  Instead the
 784pre-multiplied pixel values will be gamma encoded but
 785the alpha channel will still be linear.  This may
 786actually match the requirements of some broken software,
 787but it is unlikely.
 788
 789While linear 8-bit data is often used it has
 790insufficient precision for any image with a reasonable
 791dynamic range.  To avoid problems, and if your software
 792supports it, use png_set_expand_16() to force all
 793components to 16 bits.
 794
 795    PNG_ALPHA_OPTIMIZED: This mode is the same
 796as PNG_ALPHA_STANDARD except that
 797completely opaque pixels are gamma encoded according to
 798the screen_gamma value.  Pixels with alpha less than 1.0
 799will still have linear components.
 800
 801Use this format if you have control over your
 802compositing software and do don't do other arithmetic
 803(such as scaling) on the data you get from libpng.  Your
 804compositing software can simply copy opaque pixels to
 805the output but still has linear values for the
 806non-opaque pixels.
 807
 808In normal compositing, where the alpha channel encodes
 809partial pixel coverage (as opposed to broad area
 810translucency), the inaccuracies of the 8-bit
 811representation of non-opaque pixels are irrelevant.
 812
 813You can also try this format if your software is broken;
 814it might look better.
 815
 816    PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD;
 817however, all component values,
 818including the alpha channel are gamma encoded.  This is
 819an appropriate format to try if your software, or more
 820likely hardware, is totally broken, i.e., if it performs
 821linear arithmetic directly on gamma encoded values.
 822
 823In most cases of broken software or hardware the bug in the final display
 824manifests as a subtle halo around composited parts of the image.  You may not
 825even perceive this as a halo; the composited part of the image may simply appear
 826separate from the background, as though it had been cut out of paper and pasted
 827on afterward.
 828
 829If you don't have to deal with bugs in software or hardware, or if you can fix
 830them, there are three recommended ways of using png_set_alpha_mode():
 831
 832   png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
 833       screen_gamma);
 834
 835You can do color correction on the result (libpng does not currently
 836support color correction internally).  When you handle the alpha channel
 837you need to undo the gamma encoding and multiply out the alpha.
 838
 839   png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
 840       screen_gamma);
 841   png_set_expand_16(png_ptr);
 842
 843If you are using the high level interface, don't call png_set_expand_16();
 844instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
 845
 846With this mode you can't do color correction, but you can do arithmetic,
 847including composition and scaling, on the data without further processing.
 848
 849   png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
 850       screen_gamma);
 851
 852You can avoid the expansion to 16-bit components with this mode, but you
 853lose the ability to scale the image or perform other linear arithmetic.
 854All you can do is compose the result onto a matching output.  Since this
 855mode is libpng-specific you also need to write your own composition
 856software.
 857
 858If you don't need, or can't handle, the alpha channel you can call
 859png_set_background() to remove it by compositing against a fixed color.  Don't
 860call png_set_strip_alpha() to do this - it will leave spurious pixel values in
 861transparent parts of this image.
 862
 863   png_set_background(png_ptr, &background_color,
 864       PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
 865
 866The background_color is an RGB or grayscale value according to the data format
 867libpng will produce for you.  Because you don't yet know the format of the PNG
 868file, if you call png_set_background at this point you must arrange for the
 869format produced by libpng to always have 8-bit or 16-bit components and then
 870store the color as an 8-bit or 16-bit color as appropriate.  The color contains
 871separate gray and RGB component values, so you can let libpng produce gray or
 872RGB output according to the input format, but low bit depth grayscale images
 873must always be converted to at least 8-bit format.  (Even though low bit depth
 874grayscale images can't have an alpha channel they can have a transparent
 875color!)
 876
 877You set the transforms you need later, either as flags to the high level
 878interface or libpng API calls for the low level interface.  For reference the
 879settings and API calls required are:
 880
 8818-bit values:
 882   PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
 883   png_set_expand(png_ptr); png_set_scale_16(png_ptr);
 884
 885   If you must get exactly the same inaccurate results
 886   produced by default in versions prior to libpng-1.5.4,
 887   use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr)
 888   instead.
 889
 89016-bit values:
 891   PNG_TRANSFORM_EXPAND_16
 892   png_set_expand_16(png_ptr);
 893
 894In either case palette image data will be expanded to RGB.  If you just want
 895color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
 896to the list.
 897
 898Calling png_set_background before the PNG file header is read will not work
 899prior to libpng-1.5.4.  Because the failure may result in unexpected warnings or
 900errors it is therefore much safer to call png_set_background after the head has
 901been read.  Unfortunately this means that prior to libpng-1.5.4 it cannot be
 902used with the high level interface.
 903
 904The high-level read interface
 905
 906At this point there are two ways to proceed; through the high-level
 907read interface, or through a sequence of low-level read operations.
 908You can use the high-level interface if (a) you are willing to read
 909the entire image into memory, and (b) the input transformations
 910you want to do are limited to the following set:
 911
 912    PNG_TRANSFORM_IDENTITY      No transformation
 913    PNG_TRANSFORM_SCALE_16      Strip 16-bit samples to
 914                                8-bit accurately
 915    PNG_TRANSFORM_STRIP_16      Chop 16-bit samples to
 916                                8-bit less accurately
 917    PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
 918    PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit
 919                                samples to bytes
 920    PNG_TRANSFORM_PACKSWAP      Change order of packed
 921                                pixels to LSB first
 922    PNG_TRANSFORM_EXPAND        Perform set_expand()
 923    PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
 924    PNG_TRANSFORM_SHIFT         Normalize pixels to the
 925                                sBIT depth
 926    PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
 927                                to BGRA
 928    PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
 929                                to AG
 930    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
 931                                to transparency
 932    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
 933    PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
 934                                to RGB (or GA to RGBA)
 935    PNG_TRANSFORM_EXPAND_16     Expand samples to 16 bits
 936
 937(This excludes setting a background color, doing gamma transformation,
 938quantizing, and setting filler.)  If this is the case, simply do this:
 939
 940    png_read_png(png_ptr, info_ptr, png_transforms, NULL)
 941
 942where png_transforms is an integer containing the bitwise OR of some
 943set of transformation flags.  This call is equivalent to png_read_info(),
 944followed the set of transformations indicated by the transform mask,
 945then png_read_image(), and finally png_read_end().
 946
 947(The final parameter of this call is not yet used.  Someday it might point
 948to transformation parameters required by some future input transform.)
 949
 950You must use png_transforms and not call any png_set_transform() functions
 951when you use png_read_png().
 952
 953After you have called png_read_png(), you can retrieve the image data
 954with
 955
 956   row_pointers = png_get_rows(png_ptr, info_ptr);
 957
 958where row_pointers is an array of pointers to the pixel data for each row:
 959
 960   png_bytep row_pointers[height];
 961
 962If you know your image size and pixel size ahead of time, you can allocate
 963row_pointers prior to calling png_read_png() with
 964
 965   if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
 966      png_error (png_ptr,
 967          "Image is too tall to process in memory");
 968
 969   if (width > PNG_UINT_32_MAX/pixel_size)
 970      png_error (png_ptr,
 971          "Image is too wide to process in memory");
 972
 973   row_pointers = png_malloc(png_ptr,
 974       height*png_sizeof(png_bytep));
 975
 976   for (int i=0; i<height, i++)
 977      row_pointers[i]=NULL;  /* security precaution */
 978
 979   for (int i=0; i<height, i++)
 980      row_pointers[i]=png_malloc(png_ptr,
 981          width*pixel_size);
 982
 983   png_set_rows(png_ptr, info_ptr, &row_pointers);
 984
 985Alternatively you could allocate your image in one big block and define
 986row_pointers[i] to point into the proper places in your block.
 987
 988If you use png_set_rows(), the application is responsible for freeing
 989row_pointers (and row_pointers[i], if they were separately allocated).
 990
 991If you don't allocate row_pointers ahead of time, png_read_png() will
 992do it, and it'll be free'ed by libpng when you call png_destroy_*().
 993
 994The low-level read interface
 995
 996If you are going the low-level route, you are now ready to read all
 997the file information up to the actual image data.  You do this with a
 998call to png_read_info().
 999
1000    png_read_info(png_ptr, info_ptr);
1001
1002This will process all chunks up to but not including the image data.
1003
1004This also copies some of the data from the PNG file into the decode structure
1005for use in later transformations.  Important information copied in is:
1006
10071) The PNG file gamma from the gAMA chunk.  This overwrites the default value
1008provided by an earlier call to png_set_gamma or png_set_alpha_mode.
1009
10102) Prior to libpng-1.5.4 the background color from a bKGd chunk.  This
1011damages the information provided by an earlier call to png_set_background
1012resulting in unexpected behavior.  Libpng-1.5.4 no longer does this.
1013
10143) The number of significant bits in each component value.  Libpng uses this to
1015optimize gamma handling by reducing the internal lookup table sizes.
1016
10174) The transparent color information from a tRNS chunk.  This can be modified by
1018a later call to png_set_tRNS.
1019
1020Querying the info structure
1021
1022Functions are used to get the information from the info_ptr once it
1023has been read.  Note that these fields may not be completely filled
1024in until png_read_end() has read the chunk data following the image.
1025
1026    png_get_IHDR(png_ptr, info_ptr, &width, &height,
1027       &bit_depth, &color_type, &interlace_type,
1028       &compression_type, &filter_method);
1029
1030    width          - holds the width of the image
1031                     in pixels (up to 2^31).
1032
1033    height         - holds the height of the image
1034                     in pixels (up to 2^31).
1035
1036    bit_depth      - holds the bit depth of one of the
1037                     image channels.  (valid values are
1038                     1, 2, 4, 8, 16 and depend also on
1039                     the color_type.  See also
1040                     significant bits (sBIT) below).
1041
1042    color_type     - describes which color/alpha channels
1043                         are present.
1044                     PNG_COLOR_TYPE_GRAY
1045                        (bit depths 1, 2, 4, 8, 16)
1046                     PNG_COLOR_TYPE_GRAY_ALPHA
1047                        (bit depths 8, 16)
1048                     PNG_COLOR_TYPE_PALETTE
1049                        (bit depths 1, 2, 4, 8)
1050                     PNG_COLOR_TYPE_RGB
1051                        (bit_depths 8, 16)
1052                     PNG_COLOR_TYPE_RGB_ALPHA
1053                        (bit_depths 8, 16)
1054
1055                     PNG_COLOR_MASK_PALETTE
1056                     PNG_COLOR_MASK_COLOR
1057                     PNG_COLOR_MASK_ALPHA
1058
1059    interlace_type - (PNG_INTERLACE_NONE or
1060                     PNG_INTERLACE_ADAM7)
1061
1062    compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1063                     for PNG 1.0)
1064
1065    filter_method  - (must be PNG_FILTER_TYPE_BASE
1066                     for PNG 1.0, and can also be
1067                     PNG_INTRAPIXEL_DIFFERENCING if
1068                     the PNG datastream is embedded in
1069                     a MNG-1.0 datastream)
1070
1071    Any or all of interlace_type, compression_type, or
1072    filter_method can be NULL if you are
1073    not interested in their values.
1074
1075    Note that png_get_IHDR() returns 32-bit data into
1076    the application's width and height variables.
1077    This is an unsafe situation if these are 16-bit
1078    variables.  In such situations, the
1079    png_get_image_width() and png_get_image_height()
1080    functions described below are safer.
1081
1082    width            = png_get_image_width(png_ptr,
1083                         info_ptr);
1084
1085    height           = png_get_image_height(png_ptr,
1086                         info_ptr);
1087
1088    bit_depth        = png_get_bit_depth(png_ptr,
1089                         info_ptr);
1090
1091    color_type       = png_get_color_type(png_ptr,
1092                         info_ptr);
1093
1094    interlace_type   = png_get_interlace_type(png_ptr,
1095                         info_ptr);
1096
1097    compression_type = png_get_compression_type(png_ptr,
1098                         info_ptr);
1099
1100    filter_method    = png_get_filter_type(png_ptr,
1101                         info_ptr);
1102
1103    channels = png_get_channels(png_ptr, info_ptr);
1104
1105    channels       - number of channels of info for the
1106                     color type (valid values are 1 (GRAY,
1107                     PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1108                     4 (RGB_ALPHA or RGB + filler byte))
1109
1110    rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1111
1112    rowbytes       - number of bytes needed to hold a row
1113
1114    signature = png_get_signature(png_ptr, info_ptr);
1115
1116    signature      - holds the signature read from the
1117                     file (if any).  The data is kept in
1118                     the same offset it would be if the
1119                     whole signature were read (i.e. if an
1120                     application had already read in 4
1121                     bytes of signature before starting
1122                     libpng, the remaining 4 bytes would
1123                     be in signature[4] through signature[7]
1124                     (see png_set_sig_bytes())).
1125
1126These are also important, but their validity depends on whether the chunk
1127has been read.  The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1128png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1129data has been read, or zero if it is missing.  The parameters to the
1130png_get_<chunk> are set directly if they are simple data types, or a
1131pointer into the info_ptr is returned for any complex types.
1132
1133    png_get_PLTE(png_ptr, info_ptr, &palette,
1134                     &num_palette);
1135
1136    palette        - the palette for the file
1137                     (array of png_color)
1138
1139    num_palette    - number of entries in the palette
1140
1141    png_get_gAMA(png_ptr, info_ptr, &file_gamma);
1142    png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
1143
1144    file_gamma     - the gamma at which the file is
1145                     written (PNG_INFO_gAMA)
1146
1147    int_file_gamma - 100,000 times the gamma at which the
1148                     file is written
1149
1150    png_get_cHRM(png_ptr, info_ptr,  &white_x, &white_y, &red_x, &red_y,
1151                     &green_x, &green_y, &blue_x, &blue_y)
1152    png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, &green_X,
1153                     &green_Y, &green_Z, &blue_X, &blue_Y, &blue_Z)
1154    png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, &int_white_y,
1155                     &int_red_x, &int_red_y, &int_green_x, &int_green_y,
1156                     &int_blue_x, &int_blue_y)
1157    png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
1158                     &int_red_Z, &int_green_X, &int_green_Y, &int_green_Z,
1159                     &int_blue_X, &int_blue_Y, &int_blue_Z)
1160
1161    {white,red,green,blue}_{x,y}
1162                     A color space encoding specified using the chromaticities
1163                     of the end points and the white point. (PNG_INFO_cHRM)
1164
1165    {red,green,blue}_{X,Y,Z}
1166                     A color space encoding specified using the encoding end
1167                     points - the CIE tristimulus specification of the intended
1168                     color of the red, green and blue channels in the PNG RGB
1169                     data.  The white point is simply the sum of the three end
1170                     points. (PNG_INFO_cHRM)
1171
1172    png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1173
1174    file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
1175                     The presence of the sRGB chunk
1176                     means that the pixel data is in the
1177                     sRGB color space.  This chunk also
1178                     implies specific values of gAMA and
1179                     cHRM.
1180
1181    png_get_iCCP(png_ptr, info_ptr, &name,
1182       &compression_type, &profile, &proflen);
1183
1184    name             - The profile name.
1185
1186    compression_type - The compression type; always
1187                       PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1188                       You may give NULL to this argument to
1189                       ignore it.
1190
1191    profile          - International Color Consortium color
1192                       profile data. May contain NULs.
1193
1194    proflen          - length of profile data in bytes.
1195
1196    png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1197
1198    sig_bit        - the number of significant bits for
1199                     (PNG_INFO_sBIT) each of the gray,
1200                     red, green, and blue channels,
1201                     whichever are appropriate for the
1202                     given color type (png_color_16)
1203
1204    png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
1205                     &num_trans, &trans_color);
1206
1207    trans_alpha    - array of alpha (transparency)
1208                     entries for palette (PNG_INFO_tRNS)
1209
1210    num_trans      - number of transparent entries
1211                     (PNG_INFO_tRNS)
1212
1213    trans_color    - graylevel or color …

Large files files are truncated, but you can click here to view the full file