Home | History | Annotate | Download | only in libpng
      1 libpng.txt - A description on how to use and modify libpng
      2 
      3  libpng version 1.2.46 - July 9, 2011
      4  Updated and distributed by Glenn Randers-Pehrson
      5  <glennrp at users.sourceforge.net>
      6  Copyright (c) 1998-2009 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.2.46 - July 9, 2011
     15  Updated and distributed by Glenn Randers-Pehrson
     16  Copyright (c) 1998-2009 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 
     31 I. Introduction
     32 
     33 This 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
     35 file: introduction, structures, reading, writing, and modification and
     36 configuration notes for various special platforms.  In addition to this
     37 file, example.c is a good starting point for using the library, as
     38 it is heavily commented and should include everything most people
     39 will need.  We assume that libpng is already installed; see the
     40 INSTALL file for instructions on how to install libpng.
     41 
     42 For examples of libpng usage, see the files "example.c", "pngtest.c",
     43 and the files in the "contrib" directory, all of which are included in
     44 the libpng distribution.
     45 
     46 Libpng was written as a companion to the PNG specification, as a way
     47 of reducing the amount of time and effort it takes to support the PNG
     48 file format in application programs.
     49 
     50 The PNG specification (second edition), November 2003, is available as
     51 a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at
     52 <http://www.w3.org/TR/2003/REC-PNG-20031110/
     53 The W3C and ISO documents have identical technical content.
     54 
     55 The PNG-1.2 specification is available at
     56 <http://www.libpng.org/pub/png/documents/>.  It is technically equivalent
     57 to the PNG specification (second edition) but has some additional material.
     58 
     59 The PNG-1.0 specification is available
     60 as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
     61 W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
     62 
     63 Some additional chunks are described in the special-purpose public chunks
     64 documents at <http://www.libpng.org/pub/png/documents/>.
     65 
     66 Other information
     67 about PNG, and the latest version of libpng, can be found at the PNG home
     68 page, <http://www.libpng.org/pub/png/>.
     69 
     70 Most users will not have to modify the library significantly; advanced
     71 users may want to modify it more.  All attempts were made to make it as
     72 complete as possible, while keeping the code easy to understand.
     73 Currently, this library only supports C.  Support for other languages
     74 is being considered.
     75 
     76 Libpng has been designed to handle multiple sessions at one time,
     77 to be easily modifiable, to be portable to the vast majority of
     78 machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
     79 to use.  The ultimate goal of libpng is to promote the acceptance of
     80 the PNG file format in whatever way possible.  While there is still
     81 work to be done (see the TODO file), libpng should cover the
     82 majority of the needs of its users.
     83 
     84 Libpng uses zlib for its compression and decompression of PNG files.
     85 Further information about zlib, and the latest version of zlib, can
     86 be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
     87 The zlib compression utility is a general purpose utility that is
     88 useful for more than PNG files, and can be used without libpng.
     89 See the documentation delivered with zlib for more details.
     90 You can usually find the source files for the zlib utility wherever you
     91 find the libpng source files.
     92 
     93 Libpng is thread safe, provided the threads are using different
     94 instances of the structures.  Each thread should have its own
     95 png_struct and png_info instances, and thus its own image.
     96 Libpng does not protect itself against two threads using the
     97 same instance of a structure.
     98 
     99 II. Structures
    100 
    101 There are two main structures that are important to libpng, png_struct
    102 and png_info.  The first, png_struct, is an internal structure that
    103 will not, for the most part, be used by a user except as the first
    104 variable passed to every libpng function call.
    105 
    106 The png_info structure is designed to provide information about the
    107 PNG file.  At one time, the fields of png_info were intended to be
    108 directly accessible to the user.  However, this tended to cause problems
    109 with applications using dynamically loaded libraries, and as a result
    110 a set of interface functions for png_info (the png_get_*() and png_set_*()
    111 functions) was developed.  The fields of png_info are still available for
    112 older applications, but it is suggested that applications use the new
    113 interfaces if at all possible.
    114 
    115 Applications that do make direct access to the members of png_struct (except
    116 for png_ptr->jmpbuf) must be recompiled whenever the library is updated,
    117 and applications that make direct access to the members of png_info must
    118 be recompiled if they were compiled or loaded with libpng version 1.0.6,
    119 in which the members were in a different order.  In version 1.0.7, the
    120 members of the png_info structure reverted to the old order, as they were
    121 in versions 0.97c through 1.0.5.  Starting with version 2.0.0, both
    122 structures are going to be hidden, and the contents of the structures will
    123 only be accessible through the png_get/png_set functions.
    124 
    125 The png.h header file is an invaluable reference for programming with libpng.
    126 And while I'm on the topic, make sure you include the libpng header file:
    127 
    128 #include <png.h>
    129 
    130 III. Reading
    131 
    132 We'll now walk you through the possible functions to call when reading
    133 in a PNG file sequentially, briefly explaining the syntax and purpose
    134 of each one.  See example.c and png.h for more detail.  While
    135 progressive reading is covered in the next section, you will still
    136 need some of the functions discussed in this section to read a PNG
    137 file.
    138 
    139 Setup
    140 
    141 You will want to do the I/O initialization(*) before you get into libpng,
    142 so if it doesn't work, you don't have much to undo.  Of course, you
    143 will also want to insure that you are, in fact, dealing with a PNG
    144 file.  Libpng provides a simple check to see if a file is a PNG file.
    145 To use it, pass in the first 1 to 8 bytes of the file to the function
    146 png_sig_cmp(), and it will return 0 (false) if the bytes match the
    147 corresponding bytes of the PNG signature, or nonzero (true) otherwise.
    148 Of course, the more bytes you pass in, the greater the accuracy of the
    149 prediction.
    150 
    151 If you are intending to keep the file pointer open for use in libpng,
    152 you must ensure you don't read more than 8 bytes from the beginning
    153 of the file, and you also have to make a call to png_set_sig_bytes_read()
    154 with the number of bytes you read from the beginning.  Libpng will
    155 then only check the bytes (if any) that your program didn't read.
    156 
    157 (*): If you are not using the standard I/O functions, you will need
    158 to replace them with custom functions.  See the discussion under
    159 Customizing libpng.
    160 
    161 
    162     FILE *fp = fopen(file_name, "rb");
    163     if (!fp)
    164     {
    165         return (ERROR);
    166     }
    167     fread(header, 1, number, fp);
    168     is_png = !png_sig_cmp(header, 0, number);
    169     if (!is_png)
    170     {
    171         return (NOT_PNG);
    172     }
    173 
    174 
    175 Next, png_struct and png_info need to be allocated and initialized.  In
    176 order to ensure that the size of these structures is correct even with a
    177 dynamically linked libpng, there are functions to initialize and
    178 allocate the structures.  We also pass the library version, optional
    179 pointers to error handling functions, and a pointer to a data struct for
    180 use by the error functions, if necessary (the pointer and functions can
    181 be NULL if the default error handlers are to be used).  See the section
    182 on Changes to Libpng below regarding the old initialization functions.
    183 The structure allocation functions quietly return NULL if they fail to
    184 create the structure, so your application should check for that.
    185 
    186     png_structp png_ptr = png_create_read_struct
    187        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
    188         user_error_fn, user_warning_fn);
    189     if (!png_ptr)
    190         return (ERROR);
    191 
    192     png_infop info_ptr = png_create_info_struct(png_ptr);
    193     if (!info_ptr)
    194     {
    195         png_destroy_read_struct(&png_ptr,
    196            (png_infopp)NULL, (png_infopp)NULL);
    197         return (ERROR);
    198     }
    199 
    200     png_infop end_info = png_create_info_struct(png_ptr);
    201     if (!end_info)
    202     {
    203         png_destroy_read_struct(&png_ptr, &info_ptr,
    204           (png_infopp)NULL);
    205         return (ERROR);
    206     }
    207 
    208 If you want to use your own memory allocation routines,
    209 define PNG_USER_MEM_SUPPORTED and use
    210 png_create_read_struct_2() instead of png_create_read_struct():
    211 
    212     png_structp png_ptr = png_create_read_struct_2
    213        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
    214         user_error_fn, user_warning_fn, (png_voidp)
    215         user_mem_ptr, user_malloc_fn, user_free_fn);
    216 
    217 The error handling routines passed to png_create_read_struct()
    218 and the memory alloc/free routines passed to png_create_struct_2()
    219 are only necessary if you are not using the libpng supplied error
    220 handling and memory alloc/free functions.
    221 
    222 When libpng encounters an error, it expects to longjmp back
    223 to your routine.  Therefore, you will need to call setjmp and pass
    224 your png_jmpbuf(png_ptr).  If you read the file from different
    225 routines, you will need to update the jmpbuf field every time you enter
    226 a new routine that will call a png_*() function.
    227 
    228 See your documentation of setjmp/longjmp for your compiler for more
    229 information on setjmp/longjmp.  See the discussion on libpng error
    230 handling in the Customizing Libpng section below for more information
    231 on the libpng error handling.  If an error occurs, and libpng longjmp's
    232 back to your setjmp, you will want to call png_destroy_read_struct() to
    233 free any memory.
    234 
    235     if (setjmp(png_jmpbuf(png_ptr)))
    236     {
    237         png_destroy_read_struct(&png_ptr, &info_ptr,
    238            &end_info);
    239         fclose(fp);
    240         return (ERROR);
    241     }
    242 
    243 If you would rather avoid the complexity of setjmp/longjmp issues,
    244 you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
    245 errors will result in a call to PNG_ABORT() which defaults to abort().
    246 
    247 Now you need to set up the input code.  The default for libpng is to
    248 use the C function fread().  If you use this, you will need to pass a
    249 valid FILE * in the function png_init_io().  Be sure that the file is
    250 opened in binary mode.  If you wish to handle reading data in another
    251 way, you need not call the png_init_io() function, but you must then
    252 implement the libpng I/O methods discussed in the Customizing Libpng
    253 section below.
    254 
    255     png_init_io(png_ptr, fp);
    256 
    257 If you had previously opened the file and read any of the signature from
    258 the beginning in order to see if this was a PNG file, you need to let
    259 libpng know that there are some bytes missing from the start of the file.
    260 
    261     png_set_sig_bytes(png_ptr, number);
    262 
    263 Setting up callback code
    264 
    265 You can set up a callback function to handle any unknown chunks in the
    266 input stream. You must supply the function
    267 
    268     read_chunk_callback(png_ptr ptr,
    269          png_unknown_chunkp chunk);
    270     {
    271        /* The unknown chunk structure contains your
    272           chunk data, along with similar data for any other
    273           unknown chunks: */
    274 
    275            png_byte name[5];
    276            png_byte *data;
    277            png_size_t size;
    278 
    279        /* Note that libpng has already taken care of
    280           the CRC handling */
    281 
    282        /* put your code here.  Search for your chunk in the
    283           unknown chunk structure, process it, and return one
    284           of the following: */
    285 
    286        return (-n); /* chunk had an error */
    287        return (0); /* did not recognize */
    288        return (n); /* success */
    289     }
    290 
    291 (You can give your function another name that you like instead of
    292 "read_chunk_callback")
    293 
    294 To inform libpng about your function, use
    295 
    296     png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
    297         read_chunk_callback);
    298 
    299 This names not only the callback function, but also a user pointer that
    300 you can retrieve with
    301 
    302     png_get_user_chunk_ptr(png_ptr);
    303 
    304 If you call the png_set_read_user_chunk_fn() function, then all unknown
    305 chunks will be saved when read, in case your callback function will need
    306 one or more of them.  This behavior can be changed with the
    307 png_set_keep_unknown_chunks() function, described below.
    308 
    309 At this point, you can set up a callback function that will be
    310 called after each row has been read, which you can use to control
    311 a progress meter or the like.  It's demonstrated in pngtest.c.
    312 You must supply a function
    313 
    314     void read_row_callback(png_ptr ptr, png_uint_32 row,
    315        int pass);
    316     {
    317       /* put your code here */
    318     }
    319 
    320 (You can give it another name that you like instead of "read_row_callback")
    321 
    322 To inform libpng about your function, use
    323 
    324     png_set_read_status_fn(png_ptr, read_row_callback);
    325 
    326 Unknown-chunk handling
    327 
    328 Now you get to set the way the library processes unknown chunks in the
    329 input PNG stream. Both known and unknown chunks will be read.  Normal
    330 behavior is that known chunks will be parsed into information in
    331 various info_ptr members while unknown chunks will be discarded. This
    332 behavior can be wasteful if your application will never use some known
    333 chunk types. To change this, you can call:
    334 
    335     png_set_keep_unknown_chunks(png_ptr, keep,
    336         chunk_list, num_chunks);
    337     keep       - 0: default unknown chunk handling
    338                  1: ignore; do not keep
    339                  2: keep only if safe-to-copy
    340                  3: keep even if unsafe-to-copy
    341                You can use these definitions:
    342                  PNG_HANDLE_CHUNK_AS_DEFAULT   0
    343                  PNG_HANDLE_CHUNK_NEVER        1
    344                  PNG_HANDLE_CHUNK_IF_SAFE      2
    345                  PNG_HANDLE_CHUNK_ALWAYS       3
    346     chunk_list - list of chunks affected (a byte string,
    347                  five bytes per chunk, NULL or '\0' if
    348                  num_chunks is 0)
    349     num_chunks - number of chunks affected; if 0, all
    350                  unknown chunks are affected.  If nonzero,
    351                  only the chunks in the list are affected
    352 
    353 Unknown chunks declared in this way will be saved as raw data onto a
    354 list of png_unknown_chunk structures.  If a chunk that is normally
    355 known to libpng is named in the list, it will be handled as unknown,
    356 according to the "keep" directive.  If a chunk is named in successive
    357 instances of png_set_keep_unknown_chunks(), the final instance will
    358 take precedence.  The IHDR and IEND chunks should not be named in
    359 chunk_list; if they are, libpng will process them normally anyway.
    360 
    361 Here is an example of the usage of png_set_keep_unknown_chunks(),
    362 where the private "vpAg" chunk will later be processed by a user chunk
    363 callback function:
    364 
    365     png_byte vpAg[5]={118, 112,  65, 103, (png_byte) '\0'};
    366 
    367     #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
    368       png_byte unused_chunks[]=
    369       {
    370         104,  73,  83,  84, (png_byte) '\0',   /* hIST */
    371         105,  84,  88, 116, (png_byte) '\0',   /* iTXt */
    372         112,  67,  65,  76, (png_byte) '\0',   /* pCAL */
    373         115,  67,  65,  76, (png_byte) '\0',   /* sCAL */
    374         115,  80,  76,  84, (png_byte) '\0',   /* sPLT */
    375         116,  73,  77,  69, (png_byte) '\0',   /* tIME */
    376       };
    377     #endif
    378 
    379     ...
    380 
    381     #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
    382       /* ignore all unknown chunks: */
    383       png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
    384       /* except for vpAg: */
    385       png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
    386       /* also ignore unused known chunks: */
    387       png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
    388          (int)sizeof(unused_chunks)/5);
    389     #endif
    390 
    391 User limits
    392 
    393 The PNG specification allows the width and height of an image to be as
    394 large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
    395 Since very few applications really need to process such large images,
    396 we have imposed an arbitrary 1-million limit on rows and columns.
    397 Larger images will be rejected immediately with a png_error() call. If
    398 you wish to override this limit, you can use
    399 
    400    png_set_user_limits(png_ptr, width_max, height_max);
    401 
    402 to set your own limits, or use width_max = height_max = 0x7fffffffL
    403 to allow all valid dimensions (libpng may reject some very large images
    404 anyway because of potential buffer overflow conditions).
    405 
    406 You should put this statement after you create the PNG structure and
    407 before calling png_read_info(), png_read_png(), or png_process_data().
    408 If you need to retrieve the limits that are being applied, use
    409 
    410    width_max = png_get_user_width_max(png_ptr);
    411    height_max = png_get_user_height_max(png_ptr);
    412 
    413 The PNG specification sets no limit on the number of ancillary chunks
    414 allowed in a PNG datastream.  You can impose a limit on the total number
    415 of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
    416 
    417    png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
    418 
    419 where 0x7fffffffL means unlimited.  You can retrieve this limit with
    420 
    421    chunk_cache_max = png_get_chunk_cache_max(png_ptr);
    422 
    423 This limit also applies to the number of buffers that can be allocated
    424 by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks.
    425 
    426 The high-level read interface
    427 
    428 At this point there are two ways to proceed; through the high-level
    429 read interface, or through a sequence of low-level read operations.
    430 You can use the high-level interface if (a) you are willing to read
    431 the entire image into memory, and (b) the input transformations
    432 you want to do are limited to the following set:
    433 
    434     PNG_TRANSFORM_IDENTITY      No transformation
    435     PNG_TRANSFORM_STRIP_16      Strip 16-bit samples to
    436                                 8 bits
    437     PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
    438     PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit
    439                                 samples to bytes
    440     PNG_TRANSFORM_PACKSWAP      Change order of packed
    441                                 pixels to LSB first
    442     PNG_TRANSFORM_EXPAND        Perform set_expand()
    443     PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
    444     PNG_TRANSFORM_SHIFT         Normalize pixels to the
    445                                 sBIT depth
    446     PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
    447                                 to BGRA
    448     PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
    449                                 to AG
    450     PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
    451                                 to transparency
    452     PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
    453     PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
    454                                 to RGB (or GA to RGBA)
    455 
    456 (This excludes setting a background color, doing gamma transformation,
    457 dithering, and setting filler.)  If this is the case, simply do this:
    458 
    459     png_read_png(png_ptr, info_ptr, png_transforms, NULL)
    460 
    461 where png_transforms is an integer containing the bitwise OR of some
    462 set of transformation flags.  This call is equivalent to png_read_info(),
    463 followed the set of transformations indicated by the transform mask,
    464 then png_read_image(), and finally png_read_end().
    465 
    466 (The final parameter of this call is not yet used.  Someday it might point
    467 to transformation parameters required by some future input transform.)
    468 
    469 You must use png_transforms and not call any png_set_transform() functions
    470 when you use png_read_png().
    471 
    472 After you have called png_read_png(), you can retrieve the image data
    473 with
    474 
    475    row_pointers = png_get_rows(png_ptr, info_ptr);
    476 
    477 where row_pointers is an array of pointers to the pixel data for each row:
    478 
    479    png_bytep row_pointers[height];
    480 
    481 If you know your image size and pixel size ahead of time, you can allocate
    482 row_pointers prior to calling png_read_png() with
    483 
    484    if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
    485       png_error (png_ptr,
    486          "Image is too tall to process in memory");
    487    if (width > PNG_UINT_32_MAX/pixel_size)
    488       png_error (png_ptr,
    489          "Image is too wide to process in memory");
    490    row_pointers = png_malloc(png_ptr,
    491       height*png_sizeof(png_bytep));
    492    for (int i=0; i<height, i++)
    493       row_pointers[i]=NULL;  /* security precaution */
    494    for (int i=0; i<height, i++)
    495       row_pointers[i]=png_malloc(png_ptr,
    496          width*pixel_size);
    497    png_set_rows(png_ptr, info_ptr, &row_pointers);
    498 
    499 Alternatively you could allocate your image in one big block and define
    500 row_pointers[i] to point into the proper places in your block.
    501 
    502 If you use png_set_rows(), the application is responsible for freeing
    503 row_pointers (and row_pointers[i], if they were separately allocated).
    504 
    505 If you don't allocate row_pointers ahead of time, png_read_png() will
    506 do it, and it'll be free'ed when you call png_destroy_*().
    507 
    508 The low-level read interface
    509 
    510 If you are going the low-level route, you are now ready to read all
    511 the file information up to the actual image data.  You do this with a
    512 call to png_read_info().
    513 
    514     png_read_info(png_ptr, info_ptr);
    515 
    516 This will process all chunks up to but not including the image data.
    517 
    518 Querying the info structure
    519 
    520 Functions are used to get the information from the info_ptr once it
    521 has been read.  Note that these fields may not be completely filled
    522 in until png_read_end() has read the chunk data following the image.
    523 
    524     png_get_IHDR(png_ptr, info_ptr, &width, &height,
    525        &bit_depth, &color_type, &interlace_type,
    526        &compression_type, &filter_method);
    527 
    528     width          - holds the width of the image
    529                      in pixels (up to 2^31).
    530     height         - holds the height of the image
    531                      in pixels (up to 2^31).
    532     bit_depth      - holds the bit depth of one of the
    533                      image channels.  (valid values are
    534                      1, 2, 4, 8, 16 and depend also on
    535                      the color_type.  See also
    536                      significant bits (sBIT) below).
    537     color_type     - describes which color/alpha channels
    538                          are present.
    539                      PNG_COLOR_TYPE_GRAY
    540                         (bit depths 1, 2, 4, 8, 16)
    541                      PNG_COLOR_TYPE_GRAY_ALPHA
    542                         (bit depths 8, 16)
    543                      PNG_COLOR_TYPE_PALETTE
    544                         (bit depths 1, 2, 4, 8)
    545                      PNG_COLOR_TYPE_RGB
    546                         (bit_depths 8, 16)
    547                      PNG_COLOR_TYPE_RGB_ALPHA
    548                         (bit_depths 8, 16)
    549 
    550                      PNG_COLOR_MASK_PALETTE
    551                      PNG_COLOR_MASK_COLOR
    552                      PNG_COLOR_MASK_ALPHA
    553 
    554     filter_method  - (must be PNG_FILTER_TYPE_BASE
    555                      for PNG 1.0, and can also be
    556                      PNG_INTRAPIXEL_DIFFERENCING if
    557                      the PNG datastream is embedded in
    558                      a MNG-1.0 datastream)
    559     compression_type - (must be PNG_COMPRESSION_TYPE_BASE
    560                      for PNG 1.0)
    561     interlace_type - (PNG_INTERLACE_NONE or
    562                      PNG_INTERLACE_ADAM7)
    563 
    564     Any or all of interlace_type, compression_type, or
    565     filter_method can be NULL if you are
    566     not interested in their values.
    567 
    568     Note that png_get_IHDR() returns 32-bit data into
    569     the application's width and height variables.
    570     This is an unsafe situation if these are 16-bit
    571     variables.  In such situations, the
    572     png_get_image_width() and png_get_image_height()
    573     functions described below are safer.
    574 
    575     width            = png_get_image_width(png_ptr,
    576                          info_ptr);
    577     height           = png_get_image_height(png_ptr,
    578                          info_ptr);
    579     bit_depth        = png_get_bit_depth(png_ptr,
    580                          info_ptr);
    581     color_type       = png_get_color_type(png_ptr,
    582                          info_ptr);
    583     filter_method    = png_get_filter_type(png_ptr,
    584                          info_ptr);
    585     compression_type = png_get_compression_type(png_ptr,
    586                          info_ptr);
    587     interlace_type   = png_get_interlace_type(png_ptr,
    588                          info_ptr);
    589 
    590     channels = png_get_channels(png_ptr, info_ptr);
    591     channels       - number of channels of info for the
    592                      color type (valid values are 1 (GRAY,
    593                      PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
    594                      4 (RGB_ALPHA or RGB + filler byte))
    595     rowbytes = png_get_rowbytes(png_ptr, info_ptr);
    596     rowbytes       - number of bytes needed to hold a row
    597 
    598     signature = png_get_signature(png_ptr, info_ptr);
    599     signature      - holds the signature read from the
    600                      file (if any).  The data is kept in
    601                      the same offset it would be if the
    602                      whole signature were read (i.e. if an
    603                      application had already read in 4
    604                      bytes of signature before starting
    605                      libpng, the remaining 4 bytes would
    606                      be in signature[4] through signature[7]
    607                      (see png_set_sig_bytes())).
    608 
    609 These are also important, but their validity depends on whether the chunk
    610 has been read.  The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
    611 png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
    612 data has been read, or zero if it is missing.  The parameters to the
    613 png_get_<chunk> are set directly if they are simple data types, or a
    614 pointer into the info_ptr is returned for any complex types.
    615 
    616     png_get_PLTE(png_ptr, info_ptr, &palette,
    617                      &num_palette);
    618     palette        - the palette for the file
    619                      (array of png_color)
    620     num_palette    - number of entries in the palette
    621 
    622     png_get_gAMA(png_ptr, info_ptr, &gamma);
    623     gamma          - the gamma the file is written
    624                      at (PNG_INFO_gAMA)
    625 
    626     png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
    627     srgb_intent    - the rendering intent (PNG_INFO_sRGB)
    628                      The presence of the sRGB chunk
    629                      means that the pixel data is in the
    630                      sRGB color space.  This chunk also
    631                      implies specific values of gAMA and
    632                      cHRM.
    633 
    634     png_get_iCCP(png_ptr, info_ptr, &name,
    635        &compression_type, &profile, &proflen);
    636     name            - The profile name.
    637     compression     - The compression type; always
    638                       PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
    639                       You may give NULL to this argument to
    640                       ignore it.
    641     profile         - International Color Consortium color
    642                       profile data. May contain NULs.
    643     proflen         - length of profile data in bytes.
    644 
    645     png_get_sBIT(png_ptr, info_ptr, &sig_bit);
    646     sig_bit        - the number of significant bits for
    647                      (PNG_INFO_sBIT) each of the gray,
    648                      red, green, and blue channels,
    649                      whichever are appropriate for the
    650                      given color type (png_color_16)
    651 
    652     png_get_tRNS(png_ptr, info_ptr, &trans, &num_trans,
    653                      &trans_values);
    654     trans          - array of transparent
    655                      entries for palette (PNG_INFO_tRNS)
    656     trans_values   - graylevel or color sample values of
    657                      the single transparent color for
    658                      non-paletted images (PNG_INFO_tRNS)
    659     num_trans      - number of transparent entries
    660                      (PNG_INFO_tRNS)
    661 
    662     png_get_hIST(png_ptr, info_ptr, &hist);
    663                      (PNG_INFO_hIST)
    664     hist           - histogram of palette (array of
    665                      png_uint_16)
    666 
    667     png_get_tIME(png_ptr, info_ptr, &mod_time);
    668     mod_time       - time image was last modified
    669                     (PNG_VALID_tIME)
    670 
    671     png_get_bKGD(png_ptr, info_ptr, &background);
    672     background     - background color (PNG_VALID_bKGD)
    673                      valid 16-bit red, green and blue
    674                      values, regardless of color_type
    675 
    676     num_comments   = png_get_text(png_ptr, info_ptr,
    677                      &text_ptr, &num_text);
    678     num_comments   - number of comments
    679     text_ptr       - array of png_text holding image
    680                      comments
    681     text_ptr[i].compression - type of compression used
    682                  on "text" PNG_TEXT_COMPRESSION_NONE
    683                            PNG_TEXT_COMPRESSION_zTXt
    684                            PNG_ITXT_COMPRESSION_NONE
    685                            PNG_ITXT_COMPRESSION_zTXt
    686     text_ptr[i].key   - keyword for comment.  Must contain
    687                          1-79 characters.
    688     text_ptr[i].text  - text comments for current
    689                          keyword.  Can be empty.
    690     text_ptr[i].text_length - length of text string,
    691                  after decompression, 0 for iTXt
    692     text_ptr[i].itxt_length - length of itxt string,
    693                  after decompression, 0 for tEXt/zTXt
    694     text_ptr[i].lang  - language of comment (empty
    695                          string for unknown).
    696     text_ptr[i].lang_key  - keyword in UTF-8
    697                          (empty string for unknown).
    698     Note that the itxt_length, lang, and lang_key
    699     members of the text_ptr structure only exist
    700     when the library is built with iTXt chunk support.
    701 
    702     num_text       - number of comments (same as
    703                      num_comments; you can put NULL here
    704                      to avoid the duplication)
    705     Note while png_set_text() will accept text, language,
    706     and translated keywords that can be NULL pointers, the
    707     structure returned by png_get_text will always contain
    708     regular zero-terminated C strings.  They might be
    709     empty strings but they will never be NULL pointers.
    710 
    711     num_spalettes = png_get_sPLT(png_ptr, info_ptr,
    712        &palette_ptr);
    713     palette_ptr    - array of palette structures holding
    714                      contents of one or more sPLT chunks
    715                      read.
    716     num_spalettes  - number of sPLT chunks read.
    717 
    718     png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
    719        &unit_type);
    720     offset_x       - positive offset from the left edge
    721                      of the screen
    722     offset_y       - positive offset from the top edge
    723                      of the screen
    724     unit_type      - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
    725 
    726     png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
    727        &unit_type);
    728     res_x          - pixels/unit physical resolution in
    729                      x direction
    730     res_y          - pixels/unit physical resolution in
    731                      x direction
    732     unit_type      - PNG_RESOLUTION_UNKNOWN,
    733                      PNG_RESOLUTION_METER
    734 
    735     png_get_sCAL(png_ptr, info_ptr, &unit, &width,
    736        &height)
    737     unit        - physical scale units (an integer)
    738     width       - width of a pixel in physical scale units
    739     height      - height of a pixel in physical scale units
    740                  (width and height are doubles)
    741 
    742     png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
    743        &height)
    744     unit        - physical scale units (an integer)
    745     width       - width of a pixel in physical scale units
    746     height      - height of a pixel in physical scale units
    747                  (width and height are strings like "2.54")
    748 
    749     num_unknown_chunks = png_get_unknown_chunks(png_ptr,
    750        info_ptr, &unknowns)
    751     unknowns          - array of png_unknown_chunk
    752                         structures holding unknown chunks
    753     unknowns[i].name  - name of unknown chunk
    754     unknowns[i].data  - data of unknown chunk
    755     unknowns[i].size  - size of unknown chunk's data
    756     unknowns[i].location - position of chunk in file
    757 
    758     The value of "i" corresponds to the order in which the
    759     chunks were read from the PNG file or inserted with the
    760     png_set_unknown_chunks() function.
    761 
    762 The data from the pHYs chunk can be retrieved in several convenient
    763 forms:
    764 
    765     res_x = png_get_x_pixels_per_meter(png_ptr,
    766        info_ptr)
    767     res_y = png_get_y_pixels_per_meter(png_ptr,
    768        info_ptr)
    769     res_x_and_y = png_get_pixels_per_meter(png_ptr,
    770        info_ptr)
    771     res_x = png_get_x_pixels_per_inch(png_ptr,
    772        info_ptr)
    773     res_y = png_get_y_pixels_per_inch(png_ptr,
    774        info_ptr)
    775     res_x_and_y = png_get_pixels_per_inch(png_ptr,
    776        info_ptr)
    777     aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
    778        info_ptr)
    779 
    780    (Each of these returns 0 [signifying "unknown"] if
    781        the data is not present or if res_x is 0;
    782        res_x_and_y is 0 if res_x != res_y)
    783 
    784 The data from the oFFs chunk can be retrieved in several convenient
    785 forms:
    786 
    787     x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
    788     y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
    789     x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
    790     y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
    791 
    792    (Each of these returns 0 [signifying "unknown" if both
    793        x and y are 0] if the data is not present or if the
    794        chunk is present but the unit is the pixel)
    795 
    796 For more information, see the png_info definition in png.h and the
    797 PNG specification for chunk contents.  Be careful with trusting
    798 rowbytes, as some of the transformations could increase the space
    799 needed to hold a row (expand, filler, gray_to_rgb, etc.).
    800 See png_read_update_info(), below.
    801 
    802 A quick word about text_ptr and num_text.  PNG stores comments in
    803 keyword/text pairs, one pair per chunk, with no limit on the number
    804 of text chunks, and a 2^31 byte limit on their size.  While there are
    805 suggested keywords, there is no requirement to restrict the use to these
    806 strings.  It is strongly suggested that keywords and text be sensible
    807 to humans (that's the point), so don't use abbreviations.  Non-printing
    808 symbols are not allowed.  See the PNG specification for more details.
    809 There is also no requirement to have text after the keyword.
    810 
    811 Keywords should be limited to 79 Latin-1 characters without leading or
    812 trailing spaces, but non-consecutive spaces are allowed within the
    813 keyword.  It is possible to have the same keyword any number of times.
    814 The text_ptr is an array of png_text structures, each holding a
    815 pointer to a language string, a pointer to a keyword and a pointer to
    816 a text string.  The text string, language code, and translated
    817 keyword may be empty or NULL pointers.  The keyword/text
    818 pairs are put into the array in the order that they are received.
    819 However, some or all of the text chunks may be after the image, so, to
    820 make sure you have read all the text chunks, don't mess with these
    821 until after you read the stuff after the image.  This will be
    822 mentioned again below in the discussion that goes with png_read_end().
    823 
    824 Input transformations
    825 
    826 After you've read the header information, you can set up the library
    827 to handle any special transformations of the image data.  The various
    828 ways to transform the data will be described in the order that they
    829 should occur.  This is important, as some of these change the color
    830 type and/or bit depth of the data, and some others only work on
    831 certain color types and bit depths.  Even though each transformation
    832 checks to see if it has data that it can do something with, you should
    833 make sure to only enable a transformation if it will be valid for the
    834 data.  For example, don't swap red and blue on grayscale data.
    835 
    836 The colors used for the background and transparency values should be
    837 supplied in the same format/depth as the current image data.  They
    838 are stored in the same format/depth as the image data in a bKGD or tRNS
    839 chunk, so this is what libpng expects for this data.  The colors are
    840 transformed to keep in sync with the image data when an application
    841 calls the png_read_update_info() routine (see below).
    842 
    843 Data will be decoded into the supplied row buffers packed into bytes
    844 unless the library has been told to transform it into another format.
    845 For example, 4 bit/pixel paletted or grayscale data will be returned
    846 2 pixels/byte with the leftmost pixel in the high-order bits of the
    847 byte, unless png_set_packing() is called.  8-bit RGB data will be stored
    848 in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
    849 is called to insert filler bytes, either before or after each RGB triplet.
    850 16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
    851 byte of the color value first, unless png_set_strip_16() is called to
    852 transform it to regular RGB RGB triplets, or png_set_filler() or
    853 png_set_add alpha() is called to insert filler bytes, either before or
    854 after each RRGGBB triplet.  Similarly, 8-bit or 16-bit grayscale data can
    855 be modified with
    856 png_set_filler(), png_set_add_alpha(), or png_set_strip_16().
    857 
    858 The following code transforms grayscale images of less than 8 to 8 bits,
    859 changes paletted images to RGB, and adds a full alpha channel if there is
    860 transparency information in a tRNS chunk.  This is most useful on
    861 grayscale images with bit depths of 2 or 4 or if there is a multiple-image
    862 viewing application that wishes to treat all images in the same way.
    863 
    864     if (color_type == PNG_COLOR_TYPE_PALETTE)
    865         png_set_palette_to_rgb(png_ptr);
    866 
    867     if (color_type == PNG_COLOR_TYPE_GRAY &&
    868         bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
    869 
    870     if (png_get_valid(png_ptr, info_ptr,
    871         PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
    872 
    873 These three functions are actually aliases for png_set_expand(), added
    874 in libpng version 1.0.4, with the function names expanded to improve code
    875 readability.  In some future version they may actually do different
    876 things.
    877 
    878 As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
    879 added.  It expands the sample depth without changing tRNS to alpha.
    880 
    881 As of libpng version 1.2.46, not all possible expansions are supported.
    882 
    883 In the following table, the 01 means grayscale with depth<8, 31 means
    884 indexed with depth<8, other numerals represent the color type, "T" means
    885 the tRNS chunk is present, A means an alpha channel is present, and O
    886 means tRNS or alpha is present but all pixels in the image are opaque.
    887 
    888   FROM  01  31   0  0T  0O   2  2T  2O   3  3T  3O  4A  4O  6A  6O 
    889    TO
    890    01    -                   
    891    31        -
    892     0    1       -           
    893    0T                -
    894    0O                    -
    895     2           GX           -
    896    2T                            -
    897    2O                                -
    898     3        1                           -
    899    3T                                        -
    900    3O                                            -
    901    4A                T                               -
    902    4O                                                    -
    903    6A               GX         TX           TX               -
    904    6O                   GX                      TX               -
    905 
    906 Within the matrix,
    907      "-" means the transformation is not supported.
    908      "X" means the transformation is obtained by png_set_expand().
    909      "1" means the transformation is obtained by
    910          png_set_expand_gray_1_2_4_to_8
    911      "G" means the transformation is obtained by
    912          png_set_gray_to_rgb().
    913      "P" means the transformation is obtained by
    914          png_set_expand_palette_to_rgb().
    915      "T" means the transformation is obtained by
    916          png_set_tRNS_to_alpha().
    917 
    918 PNG can have files with 16 bits per channel.  If you only can handle
    919 8 bits per channel, this will strip the pixels down to 8 bit.
    920 
    921     if (bit_depth == 16)
    922         png_set_strip_16(png_ptr);
    923 
    924 If, for some reason, you don't need the alpha channel on an image,
    925 and you want to remove it rather than combining it with the background
    926 (but the image author certainly had in mind that you *would* combine
    927 it with the background, so that's what you should probably do):
    928 
    929     if (color_type & PNG_COLOR_MASK_ALPHA)
    930         png_set_strip_alpha(png_ptr);
    931 
    932 In PNG files, the alpha channel in an image
    933 is the level of opacity.  If you need the alpha channel in an image to
    934 be the level of transparency instead of opacity, you can invert the
    935 alpha channel (or the tRNS chunk data) after it's read, so that 0 is
    936 fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
    937 images) is fully transparent, with
    938 
    939     png_set_invert_alpha(png_ptr);
    940 
    941 The PNG format only supports pixels with postmultiplied alpha.
    942 If you want to replace the pixels, after reading them, with pixels
    943 that have premultiplied color samples, you can do this with
    944 
    945     png_set_premultiply_alpha(png_ptr);
    946 
    947 If you do this, any input with a tRNS chunk will be expanded to
    948 have an alpha channel.
    949 
    950 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
    951 they can, resulting in, for example, 8 pixels per byte for 1 bit
    952 files.  This code expands to 1 pixel per byte without changing the
    953 values of the pixels:
    954 
    955     if (bit_depth < 8)
    956         png_set_packing(png_ptr);
    957 
    958 PNG files have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
    959 stored in a PNG image have been "scaled" or "shifted" up to the next
    960 higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
    961 to 8 bits/sample in the range [0, 255]).  However, it is also possible
    962 to convert the PNG pixel data back to the original bit depth of the
    963 image.  This call reduces the pixels back down to the original bit depth:
    964 
    965     png_color_8p sig_bit;
    966 
    967     if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
    968         png_set_shift(png_ptr, sig_bit);
    969 
    970 PNG files store 3-color pixels in red, green, blue order.  This code
    971 changes the storage of the pixels to blue, green, red:
    972 
    973     if (color_type == PNG_COLOR_TYPE_RGB ||
    974         color_type == PNG_COLOR_TYPE_RGB_ALPHA)
    975         png_set_bgr(png_ptr);
    976 
    977 PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
    978 into 4 or 8 bytes for windowing systems that need them in this format:
    979 
    980     if (color_type == PNG_COLOR_TYPE_RGB)
    981         png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
    982 
    983 where "filler" is the 8 or 16-bit number to fill with, and the location is
    984 either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
    985 you want the filler before the RGB or after.  This transformation
    986 does not affect images that already have full alpha channels.  To add an
    987 opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
    988 will generate RGBA pixels.
    989 
    990 Note that png_set_filler() does not change the color type.  If you want
    991 to do that, you can add a true alpha channel with
    992 
    993     if (color_type == PNG_COLOR_TYPE_RGB ||
    994            color_type == PNG_COLOR_TYPE_GRAY)
    995     png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
    996 
    997 where "filler" contains the alpha value to assign to each pixel.
    998 This function was added in libpng-1.2.7.
    999 
   1000 If you are reading an image with an alpha channel, and you need the
   1001 data as ARGB instead of the normal PNG format RGBA:
   1002 
   1003     if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
   1004         png_set_swap_alpha(png_ptr);
   1005 
   1006 For some uses, you may want a grayscale image to be represented as
   1007 RGB.  This code will do that conversion:
   1008 
   1009     if (color_type == PNG_COLOR_TYPE_GRAY ||
   1010         color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
   1011           png_set_gray_to_rgb(png_ptr);
   1012 
   1013 Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
   1014 with alpha.
   1015 
   1016     if (color_type == PNG_COLOR_TYPE_RGB ||
   1017         color_type == PNG_COLOR_TYPE_RGB_ALPHA)
   1018           png_set_rgb_to_gray_fixed(png_ptr, error_action,
   1019              int red_weight, int green_weight);
   1020 
   1021     error_action = 1: silently do the conversion
   1022     error_action = 2: issue a warning if the original
   1023                       image has any pixel where
   1024                       red != green or red != blue
   1025     error_action = 3: issue an error and abort the
   1026                       conversion if the original
   1027                       image has any pixel where
   1028                       red != green or red != blue
   1029 
   1030     red_weight:       weight of red component times 100000
   1031     green_weight:     weight of green component times 100000
   1032                       If either weight is negative, default
   1033                       weights (21268, 71514) are used.
   1034 
   1035 If you have set error_action = 1 or 2, you can
   1036 later check whether the image really was gray, after processing
   1037 the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
   1038 It will return a png_byte that is zero if the image was gray or
   1039 1 if there were any non-gray pixels.  bKGD and sBIT data
   1040 will be silently converted to grayscale, using the green channel
   1041 data, regardless of the error_action setting.
   1042 
   1043 With red_weight+green_weight<=100000,
   1044 the normalized graylevel is computed:
   1045 
   1046     int rw = red_weight * 65536;
   1047     int gw = green_weight * 65536;
   1048     int bw = 65536 - (rw + gw);
   1049     gray = (rw*red + gw*green + bw*blue)/65536;
   1050 
   1051 The default values approximate those recommended in the Charles
   1052 Poynton's Color FAQ, <http://www.inforamp.net/~poynton/>
   1053 Copyright (c) 1998-01-04 Charles Poynton <poynton at inforamp.net>
   1054 
   1055     Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
   1056 
   1057 Libpng approximates this with
   1058 
   1059     Y = 0.21268 * R    + 0.7151 * G    + 0.07217 * B
   1060 
   1061 which can be expressed with integers as
   1062 
   1063     Y = (6969 * R + 23434 * G + 2365 * B)/32768
   1064 
   1065 The calculation is done in a linear colorspace, if the image gamma
   1066 is known.
   1067 
   1068 If you have a grayscale and you are using png_set_expand_depth(),
   1069 png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to
   1070 a higher bit-depth, you must either supply the background color as a gray
   1071 value at the original file bit-depth (need_expand = 1) or else supply the
   1072 background color as an RGB triplet at the final, expanded bit depth
   1073 (need_expand = 0).  Similarly, if you are reading a paletted image, you
   1074 must either supply the background color as a palette index (need_expand = 1)
   1075 or as an RGB triplet that may or may not be in the palette (need_expand = 0).
   1076 
   1077     png_color_16 my_background;
   1078     png_color_16p image_background;
   1079 
   1080     if (png_get_bKGD(png_ptr, info_ptr, &image_background))
   1081         png_set_background(png_ptr, image_background,
   1082           PNG_BACKGROUND_GAMMA_FILE, 1, 1.0);
   1083     else
   1084         png_set_background(png_ptr, &my_background,
   1085           PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0);
   1086 
   1087 The png_set_background() function tells libpng to composite images
   1088 with alpha or simple transparency against the supplied background
   1089 color.  If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
   1090 you may use this color, or supply another color more suitable for
   1091 the current display (e.g., the background color from a web page).  You
   1092 need to tell libpng whether the color is in the gamma space of the
   1093 display (PNG_BACKGROUND_GAMMA_SCREEN for colors you supply), the file
   1094 (PNG_BACKGROUND_GAMMA_FILE for colors from the bKGD chunk), or one
   1095 that is neither of these gammas (PNG_BACKGROUND_GAMMA_UNIQUE - I don't
   1096 know why anyone would use this, but it's here).
   1097 
   1098 To properly display PNG images on any kind of system, the application needs
   1099 to know what the display gamma is.  Ideally, the user will know this, and
   1100 the application will allow them to set it.  One method of allowing the user
   1101 to set the display gamma separately for each system is to check for a
   1102 SCREEN_GAMMA or DISPLAY_GAMMA environment variable, which will hopefully be
   1103 correctly set.
   1104 
   1105 Note that display_gamma is the overall gamma correction required to produce
   1106 pleasing results, which depends on the lighting conditions in the surrounding
   1107 environment.  In a dim or brightly lit room, no compensation other than
   1108 the physical gamma exponent of the monitor is needed, while in a dark room
   1109 a slightly smaller exponent is better.
   1110 
   1111    double gamma, screen_gamma;
   1112 
   1113    if (/* We have a user-defined screen
   1114        gamma value */)
   1115    {
   1116       screen_gamma = user_defined_screen_gamma;
   1117    }
   1118    /* One way that applications can share the same
   1119       screen gamma value */
   1120    else if ((gamma_str = getenv("SCREEN_GAMMA"))
   1121       != NULL)
   1122    {
   1123       screen_gamma = (double)atof(gamma_str);
   1124    }
   1125    /* If we don't have another value */
   1126    else
   1127    {
   1128       screen_gamma = 2.2; /* A good guess for a
   1129            PC monitor in a bright office or a dim room */
   1130       screen_gamma = 2.0; /* A good guess for a
   1131            PC monitor in a dark room */
   1132       screen_gamma = 1.7 or 1.0;  /* A good
   1133            guess for Mac systems */
   1134    }
   1135 
   1136 The png_set_gamma() function handles gamma transformations of the data.
   1137 Pass both the file gamma and the current screen_gamma.  If the file does
   1138 not have a gamma value, you can pass one anyway if you have an idea what
   1139 it is (usually 0.45455 is a good guess for GIF images on PCs).  Note
   1140 that file gammas are inverted from screen gammas.  See the discussions
   1141 on gamma in the PNG specification for an excellent description of what
   1142 gamma is, and why all applications should support it.  It is strongly
   1143 recommended that PNG viewers support gamma correction.
   1144 
   1145    if (png_get_gAMA(png_ptr, info_ptr, &gamma))
   1146       png_set_gamma(png_ptr, screen_gamma, gamma);
   1147    else
   1148       png_set_gamma(png_ptr, screen_gamma, 0.45455);
   1149 
   1150 If you need to reduce an RGB file to a paletted file, or if a paletted
   1151 file has more entries then will fit on your screen, png_set_dither()
   1152 will do that.  Note that this is a simple match dither that merely
   1153 finds the closest color available.  This should work fairly well with
   1154 optimized palettes, and fairly badly with linear color cubes.  If you
   1155 pass a palette that is larger then maximum_colors, the file will
   1156 reduce the number of colors in the palette so it will fit into
   1157 maximum_colors.  If there is a histogram, it will use it to make
   1158 more intelligent choices when reducing the palette.  If there is no
   1159 histogram, it may not do as good a job.
   1160 
   1161    if (color_type & PNG_COLOR_MASK_COLOR)
   1162    {
   1163       if (png_get_valid(png_ptr, info_ptr,
   1164          PNG_INFO_PLTE))
   1165       {
   1166          png_uint_16p histogram = NULL;
   1167 
   1168          png_get_hIST(png_ptr, info_ptr,
   1169             &histogram);
   1170          png_set_dither(png_ptr, palette, num_palette,
   1171             max_screen_colors, histogram, 1);
   1172       }
   1173       else
   1174       {
   1175          png_color std_color_cube[MAX_SCREEN_COLORS] =
   1176             { ... colors ... };
   1177 
   1178          png_set_dither(png_ptr, std_color_cube,
   1179             MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
   1180             NULL,0);
   1181       }
   1182    }
   1183 
   1184 PNG files describe monochrome as black being zero and white being one.
   1185 The following code will reverse this (make black be one and white be
   1186 zero):
   1187 
   1188    if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
   1189       png_set_invert_mono(png_ptr);
   1190 
   1191 This function can also be used to invert grayscale and gray-alpha images:
   1192 
   1193    if (color_type == PNG_COLOR_TYPE_GRAY ||
   1194         color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
   1195       png_set_invert_mono(png_ptr);
   1196 
   1197 PNG files store 16 bit pixels in network byte order (big-endian,
   1198 ie. most significant bits first).  This code changes the storage to the
   1199 other way (little-endian, i.e. least significant bits first, the
   1200 way PCs store them):
   1201 
   1202     if (bit_depth == 16)
   1203         png_set_swap(png_ptr);
   1204 
   1205 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
   1206 need to change the order the pixels are packed into bytes, you can use:
   1207 
   1208     if (bit_depth < 8)
   1209        png_set_packswap(png_ptr);
   1210 
   1211 Finally, you can write your own transformation function if none of
   1212 the existing ones meets your needs.  This is done by setting a callback
   1213 with
   1214 
   1215     png_set_read_user_transform_fn(png_ptr,
   1216        read_transform_fn);
   1217 
   1218 You must supply the function
   1219 
   1220     void read_transform_fn(png_ptr ptr, row_info_ptr
   1221        row_info, png_bytep data)
   1222 
   1223 See pngtest.c for a working example.  Your function will be called
   1224 after all of the other transformations have been processed.
   1225 
   1226 You can also set up a pointer to a user structure for use by your
   1227 callback function, and you can inform libpng that your transform
   1228 function will change the number of channels or bit depth with the
   1229 function
   1230 
   1231     png_set_user_transform_info(png_ptr, user_ptr,
   1232        user_depth, user_channels);
   1233 
   1234 The user's application, not libpng, is responsible for allocating and
   1235 freeing any memory required for the user structure.
   1236 
   1237 You can retrieve the pointer via the function
   1238 png_get_user_transform_ptr().  For example:
   1239 
   1240     voidp read_user_transform_ptr =
   1241        png_get_user_transform_ptr(png_ptr);
   1242 
   1243 The last thing to handle is interlacing; this is covered in detail below,
   1244 but you must call the function here if you want libpng to handle expansion
   1245 of the interlaced image.
   1246 
   1247     number_of_passes = png_set_interlace_handling(png_ptr);
   1248 
   1249 After setting the transformations, libpng can update your png_info
   1250 structure to reflect any transformations you've requested with this
   1251 call.  This is most useful to update the info structure's rowbytes
   1252 field so you can use it to allocate your image memory.  This function
   1253 will also update your palette with the correct screen_gamma and
   1254 background if these have been given with the calls above.
   1255 
   1256     png_read_update_info(png_ptr, info_ptr);
   1257 
   1258 After you call png_read_update_info(), you can allocate any
   1259 memory you need to hold the image.  The row data is simply
   1260 raw byte data for all forms of images.  As the actual allocation
   1261 varies among applications, no example will be given.  If you
   1262 are allocating one large chunk, you will need to build an
   1263 array of pointers to each row, as it will be needed for some
   1264 of the functions below.
   1265 
   1266 Reading image data
   1267 
   1268 After you've allocated memory, you can read the image data.
   1269 The simplest way to do this is in one function call.  If you are
   1270 allocating enough memory to hold the whole image, you can just
   1271 call png_read_image() and libpng will read in all the image data
   1272 and put it in the memory area supplied.  You will need to pass in
   1273 an array of pointers to each row.
   1274 
   1275 This function automatically handles interlacing, so you don't need
   1276 to call png_set_interlace_handling() or call this function multiple
   1277 times, or any of that other stuff necessary with png_read_rows().
   1278 
   1279    png_read_image(png_ptr, row_pointers);
   1280 
   1281 where row_pointers is:
   1282 
   1283    png_bytep row_pointers[height];
   1284 
   1285 You can point to void or char or whatever you use for pixels.
   1286 
   1287 If you don't want to read in the whole image at once, you can
   1288 use png_read_rows() instead.  If there is no interlacing (check
   1289 interlace_type == PNG_INTERLACE_NONE), this is simple:
   1290 
   1291     png_read_rows(png_ptr, row_pointers, NULL,
   1292        number_of_rows);
   1293 
   1294 where row_pointers is the same as in the png_read_image() call.
   1295 
   1296 If you are doing this just one row at a time, you can do this with
   1297 a single row_pointer instead of an array of row_pointers:
   1298 
   1299     png_bytep row_pointer = row;
   1300     png_read_row(png_ptr, row_pointer, NULL);
   1301 
   1302 If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
   1303 get somewhat harder.  The only current (PNG Specification version 1.2)
   1304 interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7)
   1305 is a somewhat complicated 2D interlace scheme, known as Adam7, that
   1306 breaks down an image into seven smaller images of varying size, based
   1307 on an 8x8 grid.
   1308 
   1309 libpng can fill out those images or it can give them to you "as is".
   1310 If you want them filled out, there are two ways to do that.  The one
   1311 mentioned in the PNG specification is to expand each pixel to cover
   1312 those pixels that have not been read yet (the "rectangle" method).
   1313 This results in a blocky image for the first pass, which gradually
   1314 smooths out as more pixels are read.  The other method is the "sparkle"
   1315 method, where pixels are drawn only in their final locations, with the
   1316 rest of the image remaining whatever colors they were initialized to
   1317 before the start of the read.  The first method usually looks better,
   1318 but tends to be slower, as there are more pixels to put in the rows.
   1319 
   1320 If you don't want libpng to handle the interlacing details, just call
   1321 png_read_rows() seven times to read in all seven images.  Each of the
   1322 images is a valid image by itself, or they can all be combined on an
   1323 8x8 grid to form a single image (although if you intend to combine them
   1324 you would be far better off using the libpng interlace handling).
   1325 
   1326 The first pass will return an image 1/8 as wide as the entire image
   1327 (every 8th column starting in column 0) and 1/8 as high as the original
   1328 (every 8th row starting in row 0), the second will be 1/8 as wide
   1329 (starting in column 4) and 1/8 as high (also starting in row 0).  The
   1330 third pass will be 1/4 as wide (every 4th pixel starting in column 0) and
   1331 1/8 as high (every 8th row starting in row 4), and the fourth pass will
   1332 be 1/4 as wide and 1/4 as high (every 4th column starting in column 2,
   1333 and every 4th row starting in row 0).  The fifth pass will return an
   1334 image 1/2 as wide, and 1/4 as high (starting at column 0 and row 2),
   1335 while the sixth pass will be 1/2 as wide and 1/2 as high as the original
   1336 (starting in column 1 and row 0).  The seventh and final pass will be as
   1337 wide as the original, and 1/2 as high, containing all of the odd
   1338 numbered scanlines.  Phew!
   1339 
   1340 If you want libpng to expand the images, call this before calling
   1341 png_start_read_image() or png_read_update_info():
   1342 
   1343     if (interlace_type == PNG_INTERLACE_ADAM7)
   1344         number_of_passes
   1345            = png_set_interlace_handling(png_ptr);
   1346 
   1347 This will return the number of passes needed.  Currently, this
   1348 is seven, but may change if another interlace type is added.
   1349 This function can be called even if the file is not interlaced,
   1350 where it will return one pass.
   1351 
   1352 If you are not going to display the image after each pass, but are
   1353 going to wait until the entire image is read in, use the sparkle
   1354 effect.  This effect is faster and the end result of either method
   1355 is exactly the same.  If you are planning on displaying the image
   1356 after each pass, the "rectangle" effect is generally considered the
   1357 better looking one.
   1358 
   1359 If you only want the "sparkle" effect, just call png_read_rows() as
   1360 normal, with the third parameter NULL.  Make sure you make pass over
   1361 the image number_of_passes times, and you don't change the data in the
   1362 rows between calls.  You can change the locations of the data, just
   1363 not the data.  Each pass only writes the pixels appropriate for that
   1364 pass, and assumes the data from previous passes is still valid.
   1365 
   1366     png_read_rows(png_ptr, row_pointers, NULL,
   1367        number_of_rows);
   1368 
   1369 If you only want the first effect (the rectangles), do the same as
   1370 before except pass the row buffer in the third parameter, and leave
   1371 the second parameter NULL.
   1372 
   1373     png_read_rows(png_ptr, NULL, row_pointers,
   1374        number_of_rows);
   1375 
   1376 Finishing a sequential read
   1377 
   1378 After you are finished reading the image through the
   1379 low-level interface, you can finish reading the file.  If you are
   1380 interested in comments or time, which may be stored either before or
   1381 after the image data, you should pass the separate png_info struct if
   1382 you want to keep the comments from before and after the image
   1383 separate.  If you are not interested, you can pass NULL.
   1384 
   1385    png_read_end(png_ptr, end_info);
   1386 
   1387 When you are done, you can free all memory allocated by libpng like this:
   1388 
   1389    png_destroy_read_struct(&png_ptr, &info_ptr,
   1390        &end_info);
   1391 
   1392 It is also possible to individually free the info_ptr members that
   1393 point to libpng-allocated storage with the following function:
   1394 
   1395     png_free_data(png_ptr, info_ptr, mask, seq)
   1396     mask - identifies data to be freed, a mask
   1397            containing the bitwise OR of one or
   1398            more of
   1399              PNG_FREE_PLTE, PNG_FREE_TRNS,
   1400              PNG_FREE_HIST, PNG_FREE_ICCP,
   1401              PNG_FREE_PCAL, PNG_FREE_ROWS,
   1402              PNG_FREE_SCAL, PNG_FREE_SPLT,
   1403              PNG_FREE_TEXT, PNG_FREE_UNKN,
   1404            or simply PNG_FREE_ALL
   1405     seq  - sequence number of item to be freed
   1406            (-1 for all items)
   1407 
   1408 This function may be safely called when the relevant storage has
   1409 already been freed, or has not yet been allocated, or was allocated
   1410 by the user and not by libpng,  and will in those cases do nothing.
   1411 The "seq" parameter is ignored if only one item of the selected data
   1412 type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
   1413 are allowed for the data type identified in the mask, such as text or
   1414 sPLT, only the n'th item in the structure is freed, where n is "seq".
   1415 
   1416 The default behavior is only to free data that was allocated internally
   1417 by libpng.  This can be changed, so that libpng will not free the data,
   1418 or so that it will free data that was allocated by the user with png_malloc()
   1419 or png_zalloc() and passed in via a png_set_*() function, with
   1420 
   1421     png_data_freer(png_ptr, info_ptr, freer, mask)
   1422     mask   - which data elements are affected
   1423              same choices as in png_free_data()
   1424     freer  - one of
   1425                PNG_DESTROY_WILL_FREE_DATA
   1426                PNG_SET_WILL_FREE_DATA
   1427                PNG_USER_WILL_FREE_DATA
   1428 
   1429 This function only affects data that has already been allocated.
   1430 You can call this function after reading the PNG data but before calling
   1431 any png_set_*() functions, to control whether the user or the png_set_*()
   1432 function is responsible for freeing any existing data that might be present,
   1433 and again after the png_set_*() functions to control whether the user
   1434 or png_destroy_*() is supposed to free the data.  When the user assumes
   1435 responsibility for libpng-allocated data, the application must use
   1436 png_free() to free it, and when the user transfers responsibility to libpng
   1437 for data that the user has allocated, the user must have used png_malloc()
   1438 or png_zalloc() to allocate it.
   1439 
   1440 If you allocated your row_pointers in a single block, as suggested above in
   1441 the description of the high level read interface, you must not transfer
   1442 responsibility for freeing it to the png_set_rows or png_read_destroy function,
   1443 because they would also try to free the individual row_pointers[i].
   1444 
   1445 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
   1446 separately, do not transfer responsibility for freeing text_ptr to libpng,
   1447 because when libpng fills a png_text structure it combines these members with
   1448 the key member, and png_free_data() will free only text_ptr.key.  Similarly,
   1449 if you transfer responsibility for free'ing text_ptr from libpng to your
   1450 application, your application must not separately free those members.
   1451 
   1452 The png_free_data() function will turn off the "valid" flag for anything
   1453 it frees.  If you need to turn the flag off for a chunk that was freed by
   1454 your application instead of by libpng, you can use
   1455 
   1456     png_set_invalid(png_ptr, info_ptr, mask);
   1457     mask - identifies the chunks to be made invalid,
   1458            containing the bitwise OR of one or
   1459            more of
   1460              PNG_INFO_gAMA, PNG_INFO_sBIT,
   1461              PNG_INFO_cHRM, PNG_INFO_PLTE,
   1462              PNG_INFO_tRNS, PNG_INFO_bKGD,
   1463              PNG_INFO_hIST, PNG_INFO_pHYs,
   1464              PNG_INFO_oFFs, PNG_INFO_tIME,
   1465              PNG_INFO_pCAL, PNG_INFO_sRGB,
   1466              PNG_INFO_iCCP, PNG_INFO_sPLT,
   1467              PNG_INFO_sCAL, PNG_INFO_IDAT
   1468 
   1469 For a more compact example of reading a PNG image, see the file example.c.
   1470 
   1471 Reading PNG files progressively
   1472 
   1473 The progressive reader is slightly different then the non-progressive
   1474 reader.  Instead of calling png_read_info(), png_read_rows(), and
   1475 png_read_end(), you make one call to png_process_data(), which calls
   1476 callbacks when it has the info, a row, or the end of the image.  You
   1477 set up these callbacks with png_set_progressive_read_fn().  You don't
   1478 have to worry about the input/output functions of libpng, as you are
   1479 giving the library the data directly in png_process_data().  I will
   1480 assume that you have read the section on reading PNG files above,
   1481 so I will only highlight the differences (although I will show
   1482 all of the code).
   1483 
   1484 png_structp png_ptr;
   1485 png_infop info_ptr;
   1486 
   1487  /*  An example code fragment of how you would
   1488      initialize the progressive reader in your
   1489      application. */
   1490  int
   1491  initialize_png_reader()
   1492  {
   1493     png_ptr = png_create_read_struct
   1494         (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
   1495          user_error_fn, user_warning_fn);
   1496     if (!png_ptr)
   1497         return (ERROR);
   1498     info_ptr = png_create_info_struct(png_ptr);
   1499     if (!info_ptr)
   1500     {
   1501         png_destroy_read_struct(&png_ptr, (png_infopp)NULL,
   1502            (png_infopp)NULL);
   1503         return (ERROR);
   1504     }
   1505 
   1506     if (setjmp(png_jmpbuf(png_ptr)))
   1507     {
   1508         png_destroy_read_struct(&png_ptr, &info_ptr,
   1509            (png_infopp)NULL);
   1510         return (ERROR);
   1511     }
   1512 
   1513     /* This one's new.  You can provide functions
   1514        to be called when the header info is valid,
   1515        when each row is completed, and when the image
   1516        is finished.  If you aren't using all functions,
   1517        you can specify NULL parameters.  Even when all
   1518        three functions are NULL, you need to call
   1519        png_set_progressive_read_fn().  You can use
   1520        any struct as the user_ptr (cast to a void pointer
   1521        for the function call), and retrieve the pointer
   1522        from inside the callbacks using the function
   1523 
   1524           png_get_progressive_ptr(png_ptr);
   1525 
   1526        which will return a void pointer, which you have
   1527        to cast appropriately.
   1528      */
   1529     png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
   1530         info_callback, row_callback, end_callback);
   1531 
   1532     return 0;
   1533  }
   1534 
   1535  /* A code fragment that you call as you receive blocks
   1536    of data */
   1537  int
   1538  process_data(png_bytep buffer, png_uint_32 length)
   1539  {
   1540     if (setjmp(png_jmpbuf(png_ptr)))
   1541     {
   1542         png_destroy_read_struct(&png_ptr, &info_ptr,
   1543            (png_infopp)NULL);
   1544         return (ERROR);
   1545     }
   1546 
   1547     /* This one's new also.  Simply give it a chunk
   1548        of data from the file stream (in order, of
   1549        course).  On machines with segmented memory
   1550        models machines, don't give it any more than
   1551        64K.  The library seems to run fine with sizes
   1552        of 4K. Although you can give it much less if
   1553        necessary (I assume you can give it chunks of
   1554        1 byte, I haven't tried less then 256 bytes
   1555        yet).  When this function returns, you may
   1556        want to display any rows that were generated
   1557        in the row callback if you don't already do
   1558        so there.
   1559      */
   1560     png_process_data(png_ptr, info_ptr, buffer, length);
   1561     return 0;
   1562  }
   1563 
   1564  /* This function is called (as set by
   1565     png_set_progressive_read_fn() above) when enough data
   1566     has been supplied so all of the header has been
   1567     read.
   1568  */
   1569  void
   1570  info_callback(png_structp png_ptr, png_infop info)
   1571  {
   1572     /* Do any setup here, including setting any of
   1573        the transformations mentioned in the Reading
   1574        PNG files section.  For now, you _must_ call
   1575        either png_start_read_image() or
   1576        png_read_update_info() after all the
   1577        transformations are set (even if you don't set
   1578        any).  You may start getting rows before
   1579        png_process_data() returns, so this is your
   1580        last chance to prepare for that.
   1581      */
   1582  }
   1583 
   1584  /* This function is called when each row of image
   1585     data is complete */
   1586  void
   1587  row_callback(png_structp png_ptr, png_bytep new_row,
   1588     png_uint_32 row_num, int pass)
   1589  {
   1590     /* If the image is interlaced, and you turned
   1591        on the interlace handler, this function will
   1592        be called for every row in every pass.  Some
   1593        of these rows will not be changed from the
   1594        previous pass.  When the row is not changed,
   1595        the new_row variable will be NULL.  The rows
   1596        and passes are called in order, so you don't
   1597        really need the row_num and pass, but I'm
   1598        supplying them because it may make your life
   1599        easier.
   1600 
   1601        For the non-NULL rows of interlaced images,
   1602        you must call png_progressive_combine_row()
   1603        passing in the row and the old row.  You can
   1604        call this function for NULL rows (it will just
   1605        return) and for non-interlaced images (it just
   1606        does the memcpy for you) if it will make the
   1607        code easier.  Thus, you can just do this for
   1608        all cases:
   1609      */
   1610 
   1611         png_progressive_combine_row(png_ptr, old_row,
   1612           new_row);
   1613 
   1614     /* where old_row is what was displayed for
   1615        previously for the row.  Note that the first
   1616        pass (pass == 0, really) will completely cover
   1617        the old row, so the rows do not have to be
   1618        initialized.  After the first pass (and only
   1619        for interlaced images), you will have to pass
   1620        the current row, and the function will combine
   1621        the old row and the new row.
   1622     */
   1623  }
   1624 
   1625  void
   1626  end_callback(png_structp png_ptr, png_infop info)
   1627  {
   1628     /* This function is called after the whole image
   1629        has been read, including any chunks after the
   1630        image (up to and including the IEND).  You
   1631        will usually have the same info chunk as you
   1632        had in the header, although some data may have
   1633        been added to the comments and time fields.
   1634 
   1635        Most people won't do much here, perhaps setting
   1636        a flag that marks the image as finished.
   1637      */
   1638  }
   1639 
   1640 
   1641 
   1642 IV. Writing
   1643 
   1644 Much of this is very similar to reading.  However, everything of
   1645 importance is repeated here, so you won't have to constantly look
   1646 back up in the reading section to understand writing.
   1647 
   1648 Setup
   1649 
   1650 You will want to do the I/O initialization before you get into libpng,
   1651 so if it doesn't work, you don't have anything to undo. If you are not
   1652 using the standard I/O functions, you will need to replace them with
   1653 custom writing functions.  See the discussion under Customizing libpng.
   1654 
   1655     FILE *fp = fopen(file_name, "wb");
   1656     if (!fp)
   1657     {
   1658        return (ERROR);
   1659     }
   1660 
   1661 Next, png_struct and png_info need to be allocated and initialized.
   1662 As these can be both relatively large, you may not want to store these
   1663 on the stack, unless you have stack space to spare.  Of course, you
   1664 will want to check if they return NULL.  If you are also reading,
   1665 you won't want to name your read structure and your write structure
   1666 both "png_ptr"; you can call them anything you like, such as
   1667 "read_ptr" and "write_ptr".  Look at pngtest.c, for example.
   1668 
   1669     png_structp png_ptr = png_create_write_struct
   1670        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
   1671         user_error_fn, user_warning_fn);
   1672     if (!png_ptr)
   1673        return (ERROR);
   1674 
   1675     png_infop info_ptr = png_create_info_struct(png_ptr);
   1676     if (!info_ptr)
   1677     {
   1678        png_destroy_write_struct(&png_ptr,
   1679          (png_infopp)NULL);
   1680        return (ERROR);
   1681     }
   1682 
   1683 If you want to use your own memory allocation routines,
   1684 define PNG_USER_MEM_SUPPORTED and use
   1685 png_create_write_struct_2() instead of png_create_write_struct():
   1686 
   1687     png_structp png_ptr = png_create_write_struct_2
   1688        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
   1689         user_error_fn, user_warning_fn, (png_voidp)
   1690         user_mem_ptr, user_malloc_fn, user_free_fn);
   1691 
   1692 After you have these structures, you will need to set up the
   1693 error handling.  When libpng encounters an error, it expects to
   1694 longjmp() back to your routine.  Therefore, you will need to call
   1695 setjmp() and pass the png_jmpbuf(png_ptr).  If you
   1696 write the file from different routines, you will need to update
   1697 the png_jmpbuf(png_ptr) every time you enter a new routine that will
   1698 call a png_*() function.  See your documentation of setjmp/longjmp
   1699 for your compiler for more information on setjmp/longjmp.  See
   1700 the discussion on libpng error handling in the Customizing Libpng
   1701 section below for more information on the libpng error handling.
   1702 
   1703     if (setjmp(png_jmpbuf(png_ptr)))
   1704     {
   1705        png_destroy_write_struct(&png_ptr, &info_ptr);
   1706        fclose(fp);
   1707        return (ERROR);
   1708     }
   1709     ...
   1710     return;
   1711 
   1712 If you would rather avoid the complexity of setjmp/longjmp issues,
   1713 you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which case
   1714 errors will result in a call to PNG_ABORT() which defaults to abort().
   1715 
   1716 Now you need to set up the output code.  The default for libpng is to
   1717 use the C function fwrite().  If you use this, you will need to pass a
   1718 valid FILE * in the function png_init_io().  Be sure that the file is
   1719 opened in binary mode.  Again, if you wish to handle writing data in
   1720 another way, see the discussion on libpng I/O handling in the Customizing
   1721 Libpng section below.
   1722 
   1723     png_init_io(png_ptr, fp);
   1724 
   1725 If you are embedding your PNG into a datastream such as MNG, and don't
   1726 want libpng to write the 8-byte signature, or if you have already
   1727 written the signature in your application, use
   1728 
   1729     png_set_sig_bytes(png_ptr, 8);
   1730 
   1731 to inform libpng that it should not write a signature.
   1732 
   1733 Write callbacks
   1734 
   1735 At this point, you can set up a callback function that will be
   1736 called after each row has been written, which you can use to control
   1737 a progress meter or the like.  It's demonstrated in pngtest.c.
   1738 You must supply a function
   1739 
   1740     void write_row_callback(png_ptr, png_uint_32 row,
   1741        int pass);
   1742     {
   1743       /* put your code here */
   1744     }
   1745 
   1746 (You can give it another name that you like instead of "write_row_callback")
   1747 
   1748 To inform libpng about your function, use
   1749 
   1750     png_set_write_status_fn(png_ptr, write_row_callback);
   1751 
   1752 You now have the option of modifying how the compression library will
   1753 run.  The following functions are mainly for testing, but may be useful
   1754 in some cases, like if you need to write PNG files extremely fast and
   1755 are willing to give up some compression, or if you want to get the
   1756 maximum possible compression at the expense of slower writing.  If you
   1757 have no special needs in this area, let the library do what it wants by
   1758 not calling this function at all, as it has been tuned to deliver a good
   1759 speed/compression ratio. The second parameter to png_set_filter() is
   1760 the filter method, for which the only valid values are 0 (as of the
   1761 July 1999 PNG specification, version 1.2) or 64 (if you are writing
   1762 a PNG datastream that is to be embedded in a MNG datastream).  The third
   1763 parameter is a flag that indicates which filter type(s) are to be tested
   1764 for each scanline.  See the PNG specification for details on the specific
   1765 filter types.
   1766 
   1767 
   1768     /* turn on or off filtering, and/or choose
   1769        specific filters.  You can use either a single
   1770        PNG_FILTER_VALUE_NAME or the bitwise OR of one
   1771        or more PNG_FILTER_NAME masks. */
   1772     png_set_filter(png_ptr, 0,
   1773        PNG_FILTER_NONE  | PNG_FILTER_VALUE_NONE |
   1774        PNG_FILTER_SUB   | PNG_FILTER_VALUE_SUB  |
   1775        PNG_FILTER_UP    | PNG_FILTER_VALUE_UP   |
   1776        PNG_FILTER_AVG   | PNG_FILTER_VALUE_AVG  |
   1777        PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
   1778        PNG_ALL_FILTERS);
   1779 
   1780 If an application
   1781 wants to start and stop using particular filters during compression,
   1782 it should start out with all of the filters (to ensure that the previous
   1783 row of pixels will be stored in case it's needed later), and then add
   1784 and remove them after the start of compression.
   1785 
   1786 If you are writing a PNG datastream that is to be embedded in a MNG
   1787 datastream, the second parameter can be either 0 or 64.
   1788 
   1789 The png_set_compression_*() functions interface to the zlib compression
   1790 library, and should mostly be ignored unless you really know what you are
   1791 doing.  The only generally useful call is png_set_compression_level()
   1792 which changes how much time zlib spends on trying to compress the image
   1793 data.  See the Compression Library (zlib.h and algorithm.txt, distributed
   1794 with zlib) for details on the compression levels.
   1795 
   1796     /* set the zlib compression level */
   1797     png_set_compression_level(png_ptr,
   1798         Z_BEST_COMPRESSION);
   1799 
   1800     /* set other zlib parameters */
   1801     png_set_compression_mem_level(png_ptr, 8);
   1802     png_set_compression_strategy(png_ptr,
   1803         Z_DEFAULT_STRATEGY);
   1804     png_set_compression_window_bits(png_ptr, 15);
   1805     png_set_compression_method(png_ptr, 8);
   1806     png_set_compression_buffer_size(png_ptr, 8192)
   1807 
   1808 extern PNG_EXPORT(void,png_set_zbuf_size)
   1809 
   1810 Setting the contents of info for output
   1811 
   1812 You now need to fill in the png_info structure with all the data you
   1813 wish to write before the actual image.  Note that the only thing you
   1814 are allowed to write after the image is the text chunks and the time
   1815 chunk (as of PNG Specification 1.2, anyway).  See png_write_end() and
   1816 the latest PNG specification for more information on that.  If you
   1817 wish to write them before the image, fill them in now, and flag that
   1818 data as being valid.  If you want to wait until after the data, don't
   1819 fill them until png_write_end().  For all the fields in png_info and
   1820 their data types, see png.h.  For explanations of what the fields
   1821 contain, see the PNG specification.
   1822 
   1823 Some of the more important parts of the png_info are:
   1824 
   1825     png_set_IHDR(png_ptr, info_ptr, width, height,
   1826        bit_depth, color_type, interlace_type,
   1827        compression_type, filter_method)
   1828     width          - holds the width of the image
   1829                      in pixels (up to 2^31).
   1830     height         - holds the height of the image
   1831                      in pixels (up to 2^31).
   1832     bit_depth      - holds the bit depth of one of the
   1833                      image channels.
   1834                      (valid values are 1, 2, 4, 8, 16
   1835                      and depend also on the
   1836                      color_type.  See also significant
   1837                      bits (sBIT) below).
   1838     color_type     - describes which color/alpha
   1839                      channels are present.
   1840                      PNG_COLOR_TYPE_GRAY
   1841                         (bit depths 1, 2, 4, 8, 16)
   1842                      PNG_COLOR_TYPE_GRAY_ALPHA
   1843                         (bit depths 8, 16)
   1844                      PNG_COLOR_TYPE_PALETTE
   1845                         (bit depths 1, 2, 4, 8)
   1846                      PNG_COLOR_TYPE_RGB
   1847                         (bit_depths 8, 16)
   1848                      PNG_COLOR_TYPE_RGB_ALPHA
   1849                         (bit_depths 8, 16)
   1850 
   1851                      PNG_COLOR_MASK_PALETTE
   1852                      PNG_COLOR_MASK_COLOR
   1853                      PNG_COLOR_MASK_ALPHA
   1854 
   1855     interlace_type - PNG_INTERLACE_NONE or
   1856                      PNG_INTERLACE_ADAM7
   1857     compression_type - (must be
   1858                      PNG_COMPRESSION_TYPE_DEFAULT)
   1859     filter_method  - (must be PNG_FILTER_TYPE_DEFAULT
   1860                      or, if you are writing a PNG to
   1861                      be embedded in a MNG datastream,
   1862                      can also be
   1863                      PNG_INTRAPIXEL_DIFFERENCING)
   1864 
   1865 If you call png_set_IHDR(), the call must appear before any of the
   1866 other png_set_*() functions, because they might require access to some of
   1867 the IHDR settings.  The remaining png_set_*() functions can be called
   1868 in any order.
   1869 
   1870 If you wish, you can reset the compression_type, interlace_type, or
   1871 filter_method later by calling png_set_IHDR() again; if you do this, the
   1872 width, height, bit_depth, and color_type must be the same in each call.
   1873 
   1874     png_set_PLTE(png_ptr, info_ptr, palette,
   1875        num_palette);
   1876     palette        - the palette for the file
   1877                      (array of png_color)
   1878     num_palette    - number of entries in the palette
   1879 
   1880     png_set_gAMA(png_ptr, info_ptr, gamma);
   1881     gamma          - the gamma the image was created
   1882                      at (PNG_INFO_gAMA)
   1883 
   1884     png_set_sRGB(png_ptr, info_ptr, srgb_intent);
   1885     srgb_intent    - the rendering intent
   1886                      (PNG_INFO_sRGB) The presence of
   1887                      the sRGB chunk means that the pixel
   1888                      data is in the sRGB color space.
   1889                      This chunk also implies specific
   1890                      values of gAMA and cHRM.  Rendering
   1891                      intent is the CSS-1 property that
   1892                      has been defined by the International
   1893                      Color Consortium
   1894                      (http://www.color.org).
   1895                      It can be one of
   1896                      PNG_sRGB_INTENT_SATURATION,
   1897                      PNG_sRGB_INTENT_PERCEPTUAL,
   1898                      PNG_sRGB_INTENT_ABSOLUTE, or
   1899                      PNG_sRGB_INTENT_RELATIVE.
   1900 
   1901 
   1902     png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
   1903        srgb_intent);
   1904     srgb_intent    - the rendering intent
   1905                      (PNG_INFO_sRGB) The presence of the
   1906                      sRGB chunk means that the pixel
   1907                      data is in the sRGB color space.
   1908                      This function also causes gAMA and
   1909                      cHRM chunks with the specific values
   1910                      that are consistent with sRGB to be
   1911                      written.
   1912 
   1913     png_set_iCCP(png_ptr, info_ptr, name, compression_type,
   1914                       profile, proflen);
   1915     name            - The profile name.
   1916     compression     - The compression type; always
   1917                       PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
   1918                       You may give NULL to this argument to
   1919                       ignore it.
   1920     profile         - International Color Consortium color
   1921                       profile data. May contain NULs.
   1922     proflen         - length of profile data in bytes.
   1923 
   1924     png_set_sBIT(png_ptr, info_ptr, sig_bit);
   1925     sig_bit        - the number of significant bits for
   1926                      (PNG_INFO_sBIT) each of the gray, red,
   1927                      green, and blue channels, whichever are
   1928                      appropriate for the given color type
   1929                      (png_color_16)
   1930 
   1931     png_set_tRNS(png_ptr, info_ptr, trans, num_trans,
   1932        trans_values);
   1933     trans          - array of transparent
   1934                      entries for palette (PNG_INFO_tRNS)
   1935     trans_values   - graylevel or color sample values
   1936                      (in order red, green, blue) of the
   1937                      single transparent color for
   1938                      non-paletted images (PNG_INFO_tRNS)
   1939     num_trans      - number of transparent entries
   1940                      (PNG_INFO_tRNS)
   1941 
   1942     png_set_hIST(png_ptr, info_ptr, hist);
   1943                     (PNG_INFO_hIST)
   1944     hist           - histogram of palette (array of
   1945                      png_uint_16)
   1946 
   1947     png_set_tIME(png_ptr, info_ptr, mod_time);
   1948     mod_time       - time image was last modified
   1949                      (PNG_VALID_tIME)
   1950 
   1951     png_set_bKGD(png_ptr, info_ptr, background);
   1952     background     - background color (PNG_VALID_bKGD)
   1953 
   1954     png_set_text(png_ptr, info_ptr, text_ptr, num_text);
   1955     text_ptr       - array of png_text holding image
   1956                      comments
   1957     text_ptr[i].compression - type of compression used
   1958                  on "text" PNG_TEXT_COMPRESSION_NONE
   1959                            PNG_TEXT_COMPRESSION_zTXt
   1960                            PNG_ITXT_COMPRESSION_NONE
   1961                            PNG_ITXT_COMPRESSION_zTXt
   1962     text_ptr[i].key   - keyword for comment.  Must contain
   1963                  1-79 characters.
   1964     text_ptr[i].text  - text comments for current
   1965                          keyword.  Can be NULL or empty.
   1966     text_ptr[i].text_length - length of text string,
   1967                  after decompression, 0 for iTXt
   1968     text_ptr[i].itxt_length - length of itxt string,
   1969                  after decompression, 0 for tEXt/zTXt
   1970     text_ptr[i].lang  - language of comment (NULL or
   1971                          empty for unknown).
   1972     text_ptr[i].translated_keyword  - keyword in UTF-8 (NULL
   1973                          or empty for unknown).
   1974     Note that the itxt_length, lang, and lang_key
   1975     members of the text_ptr structure only exist
   1976     when the library is built with iTXt chunk support.
   1977 
   1978     num_text       - number of comments
   1979 
   1980     png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
   1981        num_spalettes);
   1982     palette_ptr    - array of png_sPLT_struct structures
   1983                      to be added to the list of palettes
   1984                      in the info structure.
   1985     num_spalettes  - number of palette structures to be
   1986                      added.
   1987 
   1988     png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
   1989         unit_type);
   1990     offset_x  - positive offset from the left
   1991                      edge of the screen
   1992     offset_y  - positive offset from the top
   1993                      edge of the screen
   1994     unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
   1995 
   1996     png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
   1997         unit_type);
   1998     res_x       - pixels/unit physical resolution
   1999                   in x direction
   2000     res_y       - pixels/unit physical resolution
   2001                   in y direction
   2002     unit_type   - PNG_RESOLUTION_UNKNOWN,
   2003                   PNG_RESOLUTION_METER
   2004 
   2005     png_set_sCAL(png_ptr, info_ptr, unit, width, height)
   2006     unit        - physical scale units (an integer)
   2007     width       - width of a pixel in physical scale units
   2008     height      - height of a pixel in physical scale units
   2009                   (width and height are doubles)
   2010 
   2011     png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
   2012     unit        - physical scale units (an integer)
   2013     width       - width of a pixel in physical scale units
   2014     height      - height of a pixel in physical scale units
   2015                  (width and height are strings like "2.54")
   2016 
   2017     png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
   2018        num_unknowns)
   2019     unknowns          - array of png_unknown_chunk
   2020                         structures holding unknown chunks
   2021     unknowns[i].name  - name of unknown chunk
   2022     unknowns[i].data  - data of unknown chunk
   2023     unknowns[i].size  - size of unknown chunk's data
   2024     unknowns[i].location - position to write chunk in file
   2025                            0: do not write chunk
   2026                            PNG_HAVE_IHDR: before PLTE
   2027                            PNG_HAVE_PLTE: before IDAT
   2028                            PNG_AFTER_IDAT: after IDAT
   2029 
   2030 The "location" member is set automatically according to
   2031 what part of the output file has already been written.
   2032 You can change its value after calling png_set_unknown_chunks()
   2033 as demonstrated in pngtest.c.  Within each of the "locations",
   2034 the chunks are sequenced according to their position in the
   2035 structure (that is, the value of "i", which is the order in which
   2036 the chunk was either read from the input file or defined with
   2037 png_set_unknown_chunks).
   2038 
   2039 A quick word about text and num_text.  text is an array of png_text
   2040 structures.  num_text is the number of valid structures in the array.
   2041 Each png_text structure holds a language code, a keyword, a text value,
   2042 and a compression type.
   2043 
   2044 The compression types have the same valid numbers as the compression
   2045 types of the image data.  Currently, the only valid number is zero.
   2046 However, you can store text either compressed or uncompressed, unlike
   2047 images, which always have to be compressed.  So if you don't want the
   2048 text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
   2049 Because tEXt and zTXt chunks don't have a language field, if you
   2050 specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
   2051 any language code or translated keyword will not be written out.
   2052 
   2053 Until text gets around 1000 bytes, it is not worth compressing it.
   2054 After the text has been written out to the file, the compression type
   2055 is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
   2056 so that it isn't written out again at the end (in case you are calling
   2057 png_write_end() with the same struct.
   2058 
   2059 The keywords that are given in the PNG Specification are:
   2060 
   2061     Title            Short (one line) title or
   2062                      caption for image
   2063     Author           Name of image's creator
   2064     Description      Description of image (possibly long)
   2065     Copyright        Copyright notice
   2066     Creation Time    Time of original image creation
   2067                      (usually RFC 1123 format, see below)
   2068     Software         Software used to create the image
   2069     Disclaimer       Legal disclaimer
   2070     Warning          Warning of nature of content
   2071     Source           Device used to create the image
   2072     Comment          Miscellaneous comment; conversion
   2073                      from other image format
   2074 
   2075 The keyword-text pairs work like this.  Keywords should be short
   2076 simple descriptions of what the comment is about.  Some typical
   2077 keywords are found in the PNG specification, as is some recommendations
   2078 on keywords.  You can repeat keywords in a file.  You can even write
   2079 some text before the image and some after.  For example, you may want
   2080 to put a description of the image before the image, but leave the
   2081 disclaimer until after, so viewers working over modem connections
   2082 don't have to wait for the disclaimer to go over the modem before
   2083 they start seeing the image.  Finally, keywords should be full
   2084 words, not abbreviations.  Keywords and text are in the ISO 8859-1
   2085 (Latin-1) character set (a superset of regular ASCII) and can not
   2086 contain NUL characters, and should not contain control or other
   2087 unprintable characters.  To make the comments widely readable, stick
   2088 with basic ASCII, and avoid machine specific character set extensions
   2089 like the IBM-PC character set.  The keyword must be present, but
   2090 you can leave off the text string on non-compressed pairs.
   2091 Compressed pairs must have a text string, as only the text string
   2092 is compressed anyway, so the compression would be meaningless.
   2093 
   2094 PNG supports modification time via the png_time structure.  Two
   2095 conversion routines are provided, png_convert_from_time_t() for
   2096 time_t and png_convert_from_struct_tm() for struct tm.  The
   2097 time_t routine uses gmtime().  You don't have to use either of
   2098 these, but if you wish to fill in the png_time structure directly,
   2099 you should provide the time in universal time (GMT) if possible
   2100 instead of your local time.  Note that the year number is the full
   2101 year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
   2102 that months start with 1.
   2103 
   2104 If you want to store the time of the original image creation, you should
   2105 use a plain tEXt chunk with the "Creation Time" keyword.  This is
   2106 necessary because the "creation time" of a PNG image is somewhat vague,
   2107 depending on whether you mean the PNG file, the time the image was
   2108 created in a non-PNG format, a still photo from which the image was
   2109 scanned, or possibly the subject matter itself.  In order to facilitate
   2110 machine-readable dates, it is recommended that the "Creation Time"
   2111 tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
   2112 although this isn't a requirement.  Unlike the tIME chunk, the
   2113 "Creation Time" tEXt chunk is not expected to be automatically changed
   2114 by the software.  To facilitate the use of RFC 1123 dates, a function
   2115 png_convert_to_rfc1123(png_timep) is provided to convert from PNG
   2116 time to an RFC 1123 format string.
   2117 
   2118 Writing unknown chunks
   2119 
   2120 You can use the png_set_unknown_chunks function to queue up chunks
   2121 for writing.  You give it a chunk name, raw data, and a size; that's
   2122 all there is to it.  The chunks will be written by the next following
   2123 png_write_info_before_PLTE, png_write_info, or png_write_end function.
   2124 Any chunks previously read into the info structure's unknown-chunk
   2125 list will also be written out in a sequence that satisfies the PNG
   2126 specification's ordering rules.
   2127 
   2128 The high-level write interface
   2129 
   2130 At this point there are two ways to proceed; through the high-level
   2131 write interface, or through a sequence of low-level write operations.
   2132 You can use the high-level interface if your image data is present
   2133 in the info structure.  All defined output
   2134 transformations are permitted, enabled by the following masks.
   2135 
   2136     PNG_TRANSFORM_IDENTITY      No transformation
   2137     PNG_TRANSFORM_PACKING       Pack 1, 2 and 4-bit samples
   2138     PNG_TRANSFORM_PACKSWAP      Change order of packed
   2139                                 pixels to LSB first
   2140     PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
   2141     PNG_TRANSFORM_SHIFT         Normalize pixels to the
   2142                                 sBIT depth
   2143     PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
   2144                                 to BGRA
   2145     PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
   2146                                 to AG
   2147     PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
   2148                                 to transparency
   2149     PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
   2150     PNG_TRANSFORM_STRIP_FILLER        Strip out filler
   2151                                       bytes (deprecated).
   2152     PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
   2153                                       filler bytes
   2154     PNG_TRANSFORM_STRIP_FILLER_AFTER  Strip out trailing
   2155                                       filler bytes
   2156 
   2157 If you have valid image data in the info structure (you can use
   2158 png_set_rows() to put image data in the info structure), simply do this:
   2159 
   2160     png_write_png(png_ptr, info_ptr, png_transforms, NULL)
   2161 
   2162 where png_transforms is an integer containing the bitwise OR of some set of
   2163 transformation flags.  This call is equivalent to png_write_info(),
   2164 followed the set of transformations indicated by the transform mask,
   2165 then png_write_image(), and finally png_write_end().
   2166 
   2167 (The final parameter of this call is not yet used.  Someday it might point
   2168 to transformation parameters required by some future output transform.)
   2169 
   2170 You must use png_transforms and not call any png_set_transform() functions
   2171 when you use png_write_png().
   2172 
   2173 The low-level write interface
   2174 
   2175 If you are going the low-level route instead, you are now ready to
   2176 write all the file information up to the actual image data.  You do
   2177 this with a call to png_write_info().
   2178 
   2179     png_write_info(png_ptr, info_ptr);
   2180 
   2181 Note that there is one transformation you may need to do before
   2182 png_write_info().  In PNG files, the alpha channel in an image is the
   2183 level of opacity.  If your data is supplied as a level of transparency,
   2184 you can invert the alpha channel before you write it, so that 0 is
   2185 fully transparent and 255 (in 8-bit or paletted images) or 65535
   2186 (in 16-bit images) is fully opaque, with
   2187 
   2188     png_set_invert_alpha(png_ptr);
   2189 
   2190 This must appear before png_write_info() instead of later with the
   2191 other transformations because in the case of paletted images the tRNS
   2192 chunk data has to be inverted before the tRNS chunk is written.  If
   2193 your image is not a paletted image, the tRNS data (which in such cases
   2194 represents a single color to be rendered as transparent) won't need to
   2195 be changed, and you can safely do this transformation after your
   2196 png_write_info() call.
   2197 
   2198 If you need to write a private chunk that you want to appear before
   2199 the PLTE chunk when PLTE is present, you can write the PNG info in
   2200 two steps, and insert code to write your own chunk between them:
   2201 
   2202     png_write_info_before_PLTE(png_ptr, info_ptr);
   2203     png_set_unknown_chunks(png_ptr, info_ptr, ...);
   2204     png_write_info(png_ptr, info_ptr);
   2205 
   2206 After you've written the file information, you can set up the library
   2207 to handle any special transformations of the image data.  The various
   2208 ways to transform the data will be described in the order that they
   2209 should occur.  This is important, as some of these change the color
   2210 type and/or bit depth of the data, and some others only work on
   2211 certain color types and bit depths.  Even though each transformation
   2212 checks to see if it has data that it can do something with, you should
   2213 make sure to only enable a transformation if it will be valid for the
   2214 data.  For example, don't swap red and blue on grayscale data.
   2215 
   2216 PNG files store RGB pixels packed into 3 or 6 bytes.  This code tells
   2217 the library to strip input data that has 4 or 8 bytes per pixel down
   2218 to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
   2219 bytes per pixel).
   2220 
   2221     png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
   2222 
   2223 where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
   2224 PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
   2225 is stored XRGB or RGBX.
   2226 
   2227 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
   2228 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
   2229 If the data is supplied at 1 pixel per byte, use this code, which will
   2230 correctly pack the pixels into a single byte:
   2231 
   2232     png_set_packing(png_ptr);
   2233 
   2234 PNG files reduce possible bit depths to 1, 2, 4, 8, and 16.  If your
   2235 data is of another bit depth, you can write an sBIT chunk into the
   2236 file so that decoders can recover the original data if desired.
   2237 
   2238     /* Set the true bit depth of the image data */
   2239     if (color_type & PNG_COLOR_MASK_COLOR)
   2240     {
   2241         sig_bit.red = true_bit_depth;
   2242         sig_bit.green = true_bit_depth;
   2243         sig_bit.blue = true_bit_depth;
   2244     }
   2245     else
   2246     {
   2247         sig_bit.gray = true_bit_depth;
   2248     }
   2249     if (color_type & PNG_COLOR_MASK_ALPHA)
   2250     {
   2251         sig_bit.alpha = true_bit_depth;
   2252     }
   2253 
   2254     png_set_sBIT(png_ptr, info_ptr, &sig_bit);
   2255 
   2256 If the data is stored in the row buffer in a bit depth other than
   2257 one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
   2258 this will scale the values to appear to be the correct bit depth as
   2259 is required by PNG.
   2260 
   2261     png_set_shift(png_ptr, &sig_bit);
   2262 
   2263 PNG files store 16 bit pixels in network byte order (big-endian,
   2264 ie. most significant bits first).  This code would be used if they are
   2265 supplied the other way (little-endian, i.e. least significant bits
   2266 first, the way PCs store them):
   2267 
   2268     if (bit_depth > 8)
   2269        png_set_swap(png_ptr);
   2270 
   2271 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
   2272 need to change the order the pixels are packed into bytes, you can use:
   2273 
   2274     if (bit_depth < 8)
   2275        png_set_packswap(png_ptr);
   2276 
   2277 PNG files store 3 color pixels in red, green, blue order.  This code
   2278 would be used if they are supplied as blue, green, red:
   2279 
   2280     png_set_bgr(png_ptr);
   2281 
   2282 PNG files describe monochrome as black being zero and white being
   2283 one. This code would be used if the pixels are supplied with this reversed
   2284 (black being one and white being zero):
   2285 
   2286     png_set_invert_mono(png_ptr);
   2287 
   2288 Finally, you can write your own transformation function if none of
   2289 the existing ones meets your needs.  This is done by setting a callback
   2290 with
   2291 
   2292     png_set_write_user_transform_fn(png_ptr,
   2293        write_transform_fn);
   2294 
   2295 You must supply the function
   2296 
   2297     void write_transform_fn(png_ptr ptr, row_info_ptr
   2298        row_info, png_bytep data)
   2299 
   2300 See pngtest.c for a working example.  Your function will be called
   2301 before any of the other transformations are processed.
   2302 
   2303 You can also set up a pointer to a user structure for use by your
   2304 callback function.
   2305 
   2306     png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
   2307 
   2308 The user_channels and user_depth parameters of this function are ignored
   2309 when writing; you can set them to zero as shown.
   2310 
   2311 You can retrieve the pointer via the function png_get_user_transform_ptr().
   2312 For example:
   2313 
   2314     voidp write_user_transform_ptr =
   2315        png_get_user_transform_ptr(png_ptr);
   2316 
   2317 It is possible to have libpng flush any pending output, either manually,
   2318 or automatically after a certain number of lines have been written.  To
   2319 flush the output stream a single time call:
   2320 
   2321     png_write_flush(png_ptr);
   2322 
   2323 and to have libpng flush the output stream periodically after a certain
   2324 number of scanlines have been written, call:
   2325 
   2326     png_set_flush(png_ptr, nrows);
   2327 
   2328 Note that the distance between rows is from the last time png_write_flush()
   2329 was called, or the first row of the image if it has never been called.
   2330 So if you write 50 lines, and then png_set_flush 25, it will flush the
   2331 output on the next scanline, and every 25 lines thereafter, unless
   2332 png_write_flush() is called before 25 more lines have been written.
   2333 If nrows is too small (less than about 10 lines for a 640 pixel wide
   2334 RGB image) the image compression may decrease noticeably (although this
   2335 may be acceptable for real-time applications).  Infrequent flushing will
   2336 only degrade the compression performance by a few percent over images
   2337 that do not use flushing.
   2338 
   2339 Writing the image data
   2340 
   2341 That's it for the transformations.  Now you can write the image data.
   2342 The simplest way to do this is in one function call.  If you have the
   2343 whole image in memory, you can just call png_write_image() and libpng
   2344 will write the image.  You will need to pass in an array of pointers to
   2345 each row.  This function automatically handles interlacing, so you don't
   2346 need to call png_set_interlace_handling() or call this function multiple
   2347 times, or any of that other stuff necessary with png_write_rows().
   2348 
   2349     png_write_image(png_ptr, row_pointers);
   2350 
   2351 where row_pointers is:
   2352 
   2353     png_byte *row_pointers[height];
   2354 
   2355 You can point to void or char or whatever you use for pixels.
   2356 
   2357 If you don't want to write the whole image at once, you can
   2358 use png_write_rows() instead.  If the file is not interlaced,
   2359 this is simple:
   2360 
   2361     png_write_rows(png_ptr, row_pointers,
   2362        number_of_rows);
   2363 
   2364 row_pointers is the same as in the png_write_image() call.
   2365 
   2366 If you are just writing one row at a time, you can do this with
   2367 a single row_pointer instead of an array of row_pointers:
   2368 
   2369     png_bytep row_pointer = row;
   2370 
   2371     png_write_row(png_ptr, row_pointer);
   2372 
   2373 When the file is interlaced, things can get a good deal more complicated.
   2374 The only currently (as of the PNG Specification version 1.2, dated July
   2375 1999) defined interlacing scheme for PNG files is the "Adam7" interlace
   2376 scheme, that breaks down an image into seven smaller images of varying
   2377 size.  libpng will build these images for you, or you can do them
   2378 yourself.  If you want to build them yourself, see the PNG specification
   2379 for details of which pixels to write when.
   2380 
   2381 If you don't want libpng to handle the interlacing details, just
   2382 use png_set_interlace_handling() and call png_write_rows() the
   2383 correct number of times to write all seven sub-images.
   2384 
   2385 If you want libpng to build the sub-images, call this before you start
   2386 writing any rows:
   2387 
   2388     number_of_passes =
   2389        png_set_interlace_handling(png_ptr);
   2390 
   2391 This will return the number of passes needed.  Currently, this is seven,
   2392 but may change if another interlace type is added.
   2393 
   2394 Then write the complete image number_of_passes times.
   2395 
   2396     png_write_rows(png_ptr, row_pointers,
   2397        number_of_rows);
   2398 
   2399 As some of these rows are not used, and thus return immediately, you may
   2400 want to read about interlacing in the PNG specification, and only update
   2401 the rows that are actually used.
   2402 
   2403 Finishing a sequential write
   2404 
   2405 After you are finished writing the image, you should finish writing
   2406 the file.  If you are interested in writing comments or time, you should
   2407 pass an appropriately filled png_info pointer.  If you are not interested,
   2408 you can pass NULL.
   2409 
   2410     png_write_end(png_ptr, info_ptr);
   2411 
   2412 When you are done, you can free all memory used by libpng like this:
   2413 
   2414     png_destroy_write_struct(&png_ptr, &info_ptr);
   2415 
   2416 It is also possible to individually free the info_ptr members that
   2417 point to libpng-allocated storage with the following function:
   2418 
   2419     png_free_data(png_ptr, info_ptr, mask, seq)
   2420     mask  - identifies data to be freed, a mask
   2421             containing the bitwise OR of one or
   2422             more of
   2423               PNG_FREE_PLTE, PNG_FREE_TRNS,
   2424               PNG_FREE_HIST, PNG_FREE_ICCP,
   2425               PNG_FREE_PCAL, PNG_FREE_ROWS,
   2426               PNG_FREE_SCAL, PNG_FREE_SPLT,
   2427               PNG_FREE_TEXT, PNG_FREE_UNKN,
   2428             or simply PNG_FREE_ALL
   2429     seq   - sequence number of item to be freed
   2430             (-1 for all items)
   2431 
   2432 This function may be safely called when the relevant storage has
   2433 already been freed, or has not yet been allocated, or was allocated
   2434 by the user  and not by libpng,  and will in those cases do nothing.
   2435 The "seq" parameter is ignored if only one item of the selected data
   2436 type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
   2437 are allowed for the data type identified in the mask, such as text or
   2438 sPLT, only the n'th item in the structure is freed, where n is "seq".
   2439 
   2440 If you allocated data such as a palette that you passed in to libpng
   2441 with png_set_*, you must not free it until just before the call to
   2442 png_destroy_write_struct().
   2443 
   2444 The default behavior is only to free data that was allocated internally
   2445 by libpng.  This can be changed, so that libpng will not free the data,
   2446 or so that it will free data that was allocated by the user with png_malloc()
   2447 or png_zalloc() and passed in via a png_set_*() function, with
   2448 
   2449     png_data_freer(png_ptr, info_ptr, freer, mask)
   2450     mask   - which data elements are affected
   2451              same choices as in png_free_data()
   2452     freer  - one of
   2453                PNG_DESTROY_WILL_FREE_DATA
   2454                PNG_SET_WILL_FREE_DATA
   2455                PNG_USER_WILL_FREE_DATA
   2456 
   2457 For example, to transfer responsibility for some data from a read structure
   2458 to a write structure, you could use
   2459 
   2460     png_data_freer(read_ptr, read_info_ptr,
   2461        PNG_USER_WILL_FREE_DATA,
   2462        PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
   2463     png_data_freer(write_ptr, write_info_ptr,
   2464        PNG_DESTROY_WILL_FREE_DATA,
   2465        PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
   2466 
   2467 thereby briefly reassigning responsibility for freeing to the user but
   2468 immediately afterwards reassigning it once more to the write_destroy
   2469 function.  Having done this, it would then be safe to destroy the read
   2470 structure and continue to use the PLTE, tRNS, and hIST data in the write
   2471 structure.
   2472 
   2473 This function only affects data that has already been allocated.
   2474 You can call this function before calling after the png_set_*() functions
   2475 to control whether the user or png_destroy_*() is supposed to free the data.
   2476 When the user assumes responsibility for libpng-allocated data, the
   2477 application must use
   2478 png_free() to free it, and when the user transfers responsibility to libpng
   2479 for data that the user has allocated, the user must have used png_malloc()
   2480 or png_zalloc() to allocate it.
   2481 
   2482 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
   2483 separately, do not transfer responsibility for freeing text_ptr to libpng,
   2484 because when libpng fills a png_text structure it combines these members with
   2485 the key member, and png_free_data() will free only text_ptr.key.  Similarly,
   2486 if you transfer responsibility for free'ing text_ptr from libpng to your
   2487 application, your application must not separately free those members.
   2488 For a more compact example of writing a PNG image, see the file example.c.
   2489 
   2490 V. Modifying/Customizing libpng:
   2491 
   2492 There are two issues here.  The first is changing how libpng does
   2493 standard things like memory allocation, input/output, and error handling.
   2494 The second deals with more complicated things like adding new chunks,
   2495 adding new transformations, and generally changing how libpng works.
   2496 Both of those are compile-time issues; that is, they are generally
   2497 determined at the time the code is written, and there is rarely a need
   2498 to provide the user with a means of changing them.
   2499 
   2500 Memory allocation, input/output, and error handling
   2501 
   2502 All of the memory allocation, input/output, and error handling in libpng
   2503 goes through callbacks that are user-settable.  The default routines are
   2504 in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively.  To change
   2505 these functions, call the appropriate png_set_*_fn() function.
   2506 
   2507 Memory allocation is done through the functions png_malloc(), png_calloc(),
   2508 and png_free().  These currently just call the standard C functions.
   2509 png_calloc() calls png_malloc() and then png_memset() to clear the newly
   2510 allocated memory to zero.  If your pointers can't access more then 64K
   2511 at a time, you will want to set MAXSEG_64K in zlib.h.  Since it is
   2512 unlikely that the method of handling memory allocation on a platform
   2513 will change between applications, these functions must be modified in
   2514 the library at compile time.  If you prefer to use a different method
   2515 of allocating and freeing data, you can use png_create_read_struct_2() or
   2516 png_create_write_struct_2() to register your own functions as described
   2517 above.  These functions also provide a void pointer that can be retrieved
   2518 via
   2519 
   2520     mem_ptr=png_get_mem_ptr(png_ptr);
   2521 
   2522 Your replacement memory functions must have prototypes as follows:
   2523 
   2524     png_voidp malloc_fn(png_structp png_ptr,
   2525        png_size_t size);
   2526     void free_fn(png_structp png_ptr, png_voidp ptr);
   2527 
   2528 Your malloc_fn() must return NULL in case of failure.  The png_malloc()
   2529 function will normally call png_error() if it receives a NULL from the
   2530 system memory allocator or from your replacement malloc_fn().
   2531 
   2532 Your free_fn() will never be called with a NULL ptr, since libpng's
   2533 png_free() checks for NULL before calling free_fn().
   2534 
   2535 Input/Output in libpng is done through png_read() and png_write(),
   2536 which currently just call fread() and fwrite().  The FILE * is stored in
   2537 png_struct and is initialized via png_init_io().  If you wish to change
   2538 the method of I/O, the library supplies callbacks that you can set
   2539 through the function png_set_read_fn() and png_set_write_fn() at run
   2540 time, instead of calling the png_init_io() function.  These functions
   2541 also provide a void pointer that can be retrieved via the function
   2542 png_get_io_ptr().  For example:
   2543 
   2544     png_set_read_fn(png_structp read_ptr,
   2545         voidp read_io_ptr, png_rw_ptr read_data_fn)
   2546 
   2547     png_set_write_fn(png_structp write_ptr,
   2548         voidp write_io_ptr, png_rw_ptr write_data_fn,
   2549         png_flush_ptr output_flush_fn);
   2550 
   2551     voidp read_io_ptr = png_get_io_ptr(read_ptr);
   2552     voidp write_io_ptr = png_get_io_ptr(write_ptr);
   2553 
   2554 The replacement I/O functions must have prototypes as follows:
   2555 
   2556     void user_read_data(png_structp png_ptr,
   2557         png_bytep data, png_size_t length);
   2558     void user_write_data(png_structp png_ptr,
   2559         png_bytep data, png_size_t length);
   2560     void user_flush_data(png_structp png_ptr);
   2561 
   2562 The user_read_data() function is responsible for detecting and
   2563 handling end-of-data errors.
   2564 
   2565 Supplying NULL for the read, write, or flush functions sets them back
   2566 to using the default C stream functions, which expect the io_ptr to
   2567 point to a standard *FILE structure.  It is probably a mistake
   2568 to use NULL for one of write_data_fn and output_flush_fn but not both
   2569 of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
   2570 It is an error to read from a write stream, and vice versa.
   2571 
   2572 Error handling in libpng is done through png_error() and png_warning().
   2573 Errors handled through png_error() are fatal, meaning that png_error()
   2574 should never return to its caller.  Currently, this is handled via
   2575 setjmp() and longjmp() (unless you have compiled libpng with
   2576 PNG_SETJMP_NOT_SUPPORTED, in which case it is handled via PNG_ABORT()),
   2577 but you could change this to do things like exit() if you should wish.
   2578 
   2579 On non-fatal errors, png_warning() is called
   2580 to print a warning message, and then control returns to the calling code.
   2581 By default png_error() and png_warning() print a message on stderr via
   2582 fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
   2583 (because you don't want the messages) or PNG_NO_STDIO defined (because
   2584 fprintf() isn't available).  If you wish to change the behavior of the error
   2585 functions, you will need to set up your own message callbacks.  These
   2586 functions are normally supplied at the time that the png_struct is created.
   2587 It is also possible to redirect errors and warnings to your own replacement
   2588 functions after png_create_*_struct() has been called by calling:
   2589 
   2590     png_set_error_fn(png_structp png_ptr,
   2591         png_voidp error_ptr, png_error_ptr error_fn,
   2592         png_error_ptr warning_fn);
   2593 
   2594     png_voidp error_ptr = png_get_error_ptr(png_ptr);
   2595 
   2596 If NULL is supplied for either error_fn or warning_fn, then the libpng
   2597 default function will be used, calling fprintf() and/or longjmp() if a
   2598 problem is encountered.  The replacement error functions should have
   2599 parameters as follows:
   2600 
   2601     void user_error_fn(png_structp png_ptr,
   2602         png_const_charp error_msg);
   2603     void user_warning_fn(png_structp png_ptr,
   2604         png_const_charp warning_msg);
   2605 
   2606 The motivation behind using setjmp() and longjmp() is the C++ throw and
   2607 catch exception handling methods.  This makes the code much easier to write,
   2608 as there is no need to check every return code of every function call.
   2609 However, there are some uncertainties about the status of local variables
   2610 after a longjmp, so the user may want to be careful about doing anything
   2611 after setjmp returns non-zero besides returning itself.  Consult your
   2612 compiler documentation for more details.  For an alternative approach, you
   2613 may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net).
   2614 
   2615 Custom chunks
   2616 
   2617 If you need to read or write custom chunks, you may need to get deeper
   2618 into the libpng code.  The library now has mechanisms for storing
   2619 and writing chunks of unknown type; you can even declare callbacks
   2620 for custom chunks.  However, this may not be good enough if the
   2621 library code itself needs to know about interactions between your
   2622 chunk and existing `intrinsic' chunks.
   2623 
   2624 If you need to write a new intrinsic chunk, first read the PNG
   2625 specification. Acquire a first level of understanding of how it works.
   2626 Pay particular attention to the sections that describe chunk names,
   2627 and look at how other chunks were designed, so you can do things
   2628 similarly.  Second, check out the sections of libpng that read and
   2629 write chunks.  Try to find a chunk that is similar to yours and use
   2630 it as a template.  More details can be found in the comments inside
   2631 the code.  It is best to handle unknown chunks in a generic method,
   2632 via callback functions, instead of by modifying libpng functions.
   2633 
   2634 If you wish to write your own transformation for the data, look through
   2635 the part of the code that does the transformations, and check out some of
   2636 the simpler ones to get an idea of how they work.  Try to find a similar
   2637 transformation to the one you want to add and copy off of it.  More details
   2638 can be found in the comments inside the code itself.
   2639 
   2640 Configuring for 16 bit platforms
   2641 
   2642 You will want to look into zconf.h to tell zlib (and thus libpng) that
   2643 it cannot allocate more then 64K at a time.  Even if you can, the memory
   2644 won't be accessible.  So limit zlib and libpng to 64K by defining MAXSEG_64K.
   2645 
   2646 Configuring for DOS
   2647 
   2648 For DOS users who only have access to the lower 640K, you will
   2649 have to limit zlib's memory usage via a png_set_compression_mem_level()
   2650 call.  See zlib.h or zconf.h in the zlib library for more information.
   2651 
   2652 Configuring for Medium Model
   2653 
   2654 Libpng's support for medium model has been tested on most of the popular
   2655 compilers.  Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
   2656 defined, and FAR gets defined to far in pngconf.h, and you should be
   2657 all set.  Everything in the library (except for zlib's structure) is
   2658 expecting far data.  You must use the typedefs with the p or pp on
   2659 the end for pointers (or at least look at them and be careful).  Make
   2660 note that the rows of data are defined as png_bytepp, which is an
   2661 unsigned char far * far *.
   2662 
   2663 Configuring for gui/windowing platforms:
   2664 
   2665 You will need to write new error and warning functions that use the GUI
   2666 interface, as described previously, and set them to be the error and
   2667 warning functions at the time that png_create_*_struct() is called,
   2668 in order to have them available during the structure initialization.
   2669 They can be changed later via png_set_error_fn().  On some compilers,
   2670 you may also have to change the memory allocators (png_malloc, etc.).
   2671 
   2672 Configuring for compiler xxx:
   2673 
   2674 All includes for libpng are in pngconf.h.  If you need to add, change
   2675 or delete an include, this is the place to do it.
   2676 The includes that are not needed outside libpng are protected by the
   2677 PNG_INTERNAL definition, which is only defined for those routines inside
   2678 libpng itself.  The files in libpng proper only include png.h, which
   2679 includes pngconf.h.
   2680 
   2681 Configuring zlib:
   2682 
   2683 There are special functions to configure the compression.  Perhaps the
   2684 most useful one changes the compression level, which currently uses
   2685 input compression values in the range 0 - 9.  The library normally
   2686 uses the default compression level (Z_DEFAULT_COMPRESSION = 6).  Tests
   2687 have shown that for a large majority of images, compression values in
   2688 the range 3-6 compress nearly as well as higher levels, and do so much
   2689 faster.  For online applications it may be desirable to have maximum speed
   2690 (Z_BEST_SPEED = 1).  With versions of zlib after v0.99, you can also
   2691 specify no compression (Z_NO_COMPRESSION = 0), but this would create
   2692 files larger than just storing the raw bitmap.  You can specify the
   2693 compression level by calling:
   2694 
   2695     png_set_compression_level(png_ptr, level);
   2696 
   2697 Another useful one is to reduce the memory level used by the library.
   2698 The memory level defaults to 8, but it can be lowered if you are
   2699 short on memory (running DOS, for example, where you only have 640K).
   2700 Note that the memory level does have an effect on compression; among
   2701 other things, lower levels will result in sections of incompressible
   2702 data being emitted in smaller stored blocks, with a correspondingly
   2703 larger relative overhead of up to 15% in the worst case.
   2704 
   2705     png_set_compression_mem_level(png_ptr, level);
   2706 
   2707 The other functions are for configuring zlib.  They are not recommended
   2708 for normal use and may result in writing an invalid PNG file.  See
   2709 zlib.h for more information on what these mean.
   2710 
   2711     png_set_compression_strategy(png_ptr,
   2712         strategy);
   2713     png_set_compression_window_bits(png_ptr,
   2714         window_bits);
   2715     png_set_compression_method(png_ptr, method);
   2716     png_set_compression_buffer_size(png_ptr, size);
   2717 
   2718 Controlling row filtering
   2719 
   2720 If you want to control whether libpng uses filtering or not, which
   2721 filters are used, and how it goes about picking row filters, you
   2722 can call one of these functions.  The selection and configuration
   2723 of row filters can have a significant impact on the size and
   2724 encoding speed and a somewhat lesser impact on the decoding speed
   2725 of an image.  Filtering is enabled by default for RGB and grayscale
   2726 images (with and without alpha), but not for paletted images nor
   2727 for any images with bit depths less than 8 bits/pixel.
   2728 
   2729 The 'method' parameter sets the main filtering method, which is
   2730 currently only '0' in the PNG 1.2 specification.  The 'filters'
   2731 parameter sets which filter(s), if any, should be used for each
   2732 scanline.  Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
   2733 to turn filtering on and off, respectively.
   2734 
   2735 Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
   2736 PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
   2737 ORed together with '|' to specify one or more filters to use.
   2738 These filters are described in more detail in the PNG specification.
   2739 If you intend to change the filter type during the course of writing
   2740 the image, you should start with flags set for all of the filters
   2741 you intend to use so that libpng can initialize its internal
   2742 structures appropriately for all of the filter types.  (Note that this
   2743 means the first row must always be adaptively filtered, because libpng
   2744 currently does not allocate the filter buffers until png_write_row()
   2745 is called for the first time.)
   2746 
   2747     filters = PNG_FILTER_NONE | PNG_FILTER_SUB
   2748               PNG_FILTER_UP | PNG_FILTER_AVG |
   2749               PNG_FILTER_PAETH | PNG_ALL_FILTERS;
   2750 
   2751     png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
   2752        filters);
   2753               The second parameter can also be
   2754               PNG_INTRAPIXEL_DIFFERENCING if you are
   2755               writing a PNG to be embedded in a MNG
   2756               datastream.  This parameter must be the
   2757               same as the value of filter_method used
   2758               in png_set_IHDR().
   2759 
   2760 It is also possible to influence how libpng chooses from among the
   2761 available filters.  This is done in one or both of two ways - by
   2762 telling it how important it is to keep the same filter for successive
   2763 rows, and by telling it the relative computational costs of the filters.
   2764 
   2765     double weights[3] = {1.5, 1.3, 1.1},
   2766        costs[PNG_FILTER_VALUE_LAST] =
   2767        {1.0, 1.3, 1.3, 1.5, 1.7};
   2768 
   2769     png_set_filter_heuristics(png_ptr,
   2770        PNG_FILTER_HEURISTIC_WEIGHTED, 3,
   2771        weights, costs);
   2772 
   2773 The weights are multiplying factors that indicate to libpng that the
   2774 row filter should be the same for successive rows unless another row filter
   2775 is that many times better than the previous filter.  In the above example,
   2776 if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
   2777 "sum of absolute differences" 1.5 x 1.3 times higher than other filters
   2778 and still be chosen, while the NONE filter could have a sum 1.1 times
   2779 higher than other filters and still be chosen.  Unspecified weights are
   2780 taken to be 1.0, and the specified weights should probably be declining
   2781 like those above in order to emphasize recent filters over older filters.
   2782 
   2783 The filter costs specify for each filter type a relative decoding cost
   2784 to be considered when selecting row filters.  This means that filters
   2785 with higher costs are less likely to be chosen over filters with lower
   2786 costs, unless their "sum of absolute differences" is that much smaller.
   2787 The costs do not necessarily reflect the exact computational speeds of
   2788 the various filters, since this would unduly influence the final image
   2789 size.
   2790 
   2791 Note that the numbers above were invented purely for this example and
   2792 are given only to help explain the function usage.  Little testing has
   2793 been done to find optimum values for either the costs or the weights.
   2794 
   2795 Removing unwanted object code
   2796 
   2797 There are a bunch of #define's in pngconf.h that control what parts of
   2798 libpng are compiled.  All the defines end in _SUPPORTED.  If you are
   2799 never going to use a capability, you can change the #define to #undef
   2800 before recompiling libpng and save yourself code and data space, or
   2801 you can turn off individual capabilities with defines that begin with
   2802 PNG_NO_.
   2803 
   2804 You can also turn all of the transforms and ancillary chunk capabilities
   2805 off en masse with compiler directives that define
   2806 PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
   2807 or all four,
   2808 along with directives to turn on any of the capabilities that you do
   2809 want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
   2810 transformations but still leave the library fully capable of reading
   2811 and writing PNG files with all known public chunks. Use of the
   2812 PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
   2813 that is incapable of reading or writing ancillary chunks.  If you are
   2814 not using the progressive reading capability, you can turn that off
   2815 with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
   2816 capability, which you'll still have).
   2817 
   2818 All the reading and writing specific code are in separate files, so the
   2819 linker should only grab the files it needs.  However, if you want to
   2820 make sure, or if you are building a stand alone library, all the
   2821 reading files start with pngr and all the writing files start with
   2822 pngw.  The files that don't match either (like png.c, pngtrans.c, etc.)
   2823 are used for both reading and writing, and always need to be included.
   2824 The progressive reader is in pngpread.c
   2825 
   2826 If you are creating or distributing a dynamically linked library (a .so
   2827 or DLL file), you should not remove or disable any parts of the library,
   2828 as this will cause applications linked with different versions of the
   2829 library to fail if they call functions not available in your library.
   2830 The size of the library itself should not be an issue, because only
   2831 those sections that are actually used will be loaded into memory.
   2832 
   2833 Requesting debug printout
   2834 
   2835 The macro definition PNG_DEBUG can be used to request debugging
   2836 printout.  Set it to an integer value in the range 0 to 3.  Higher
   2837 numbers result in increasing amounts of debugging information.  The
   2838 information is printed to the "stderr" file, unless another file
   2839 name is specified in the PNG_DEBUG_FILE macro definition.
   2840 
   2841 When PNG_DEBUG > 0, the following functions (macros) become available:
   2842 
   2843    png_debug(level, message)
   2844    png_debug1(level, message, p1)
   2845    png_debug2(level, message, p1, p2)
   2846 
   2847 in which "level" is compared to PNG_DEBUG to decide whether to print
   2848 the message, "message" is the formatted string to be printed,
   2849 and p1 and p2 are parameters that are to be embedded in the string
   2850 according to printf-style formatting directives.  For example,
   2851 
   2852    png_debug1(2, "foo=%d\n", foo);
   2853 
   2854 is expanded to
   2855 
   2856    if(PNG_DEBUG > 2)
   2857      fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
   2858 
   2859 When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
   2860 can still use PNG_DEBUG to control your own debugging:
   2861 
   2862    #ifdef PNG_DEBUG
   2863        fprintf(stderr, ...
   2864    #endif
   2865 
   2866 When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
   2867 having level = 0 will be printed.  There aren't any such statements in
   2868 this version of libpng, but if you insert some they will be printed.
   2869 
   2870 VI.  MNG support
   2871 
   2872 The MNG specification (available at http://www.libpng.org/pub/mng) allows
   2873 certain extensions to PNG for PNG images that are embedded in MNG datastreams.
   2874 Libpng can support some of these extensions.  To enable them, use the
   2875 png_permit_mng_features() function:
   2876 
   2877    feature_set = png_permit_mng_features(png_ptr, mask)
   2878    mask is a png_uint_32 containing the bitwise OR of the
   2879         features you want to enable.  These include
   2880         PNG_FLAG_MNG_EMPTY_PLTE
   2881         PNG_FLAG_MNG_FILTER_64
   2882         PNG_ALL_MNG_FEATURES
   2883    feature_set is a png_uint_32 that is the bitwise AND of
   2884       your mask with the set of MNG features that is
   2885       supported by the version of libpng that you are using.
   2886 
   2887 It is an error to use this function when reading or writing a standalone
   2888 PNG file with the PNG 8-byte signature.  The PNG datastream must be wrapped
   2889 in a MNG datastream.  As a minimum, it must have the MNG 8-byte signature
   2890 and the MHDR and MEND chunks.  Libpng does not provide support for these
   2891 or any other MNG chunks; your application must provide its own support for
   2892 them.  You may wish to consider using libmng (available at
   2893 http://www.libmng.com) instead.
   2894 
   2895 VII.  Changes to Libpng from version 0.88
   2896 
   2897 It should be noted that versions of libpng later than 0.96 are not
   2898 distributed by the original libpng author, Guy Schalnat, nor by
   2899 Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
   2900 distributed versions 0.89 through 0.96, but rather by another member
   2901 of the original PNG Group, Glenn Randers-Pehrson.  Guy and Andreas are
   2902 still alive and well, but they have moved on to other things.
   2903 
   2904 The old libpng functions png_read_init(), png_write_init(),
   2905 png_info_init(), png_read_destroy(), and png_write_destroy() have been
   2906 moved to PNG_INTERNAL in version 0.95 to discourage their use.  These
   2907 functions will be removed from libpng version 2.0.0.
   2908 
   2909 The preferred method of creating and initializing the libpng structures is
   2910 via the png_create_read_struct(), png_create_write_struct(), and
   2911 png_create_info_struct() because they isolate the size of the structures
   2912 from the application, allow version error checking, and also allow the
   2913 use of custom error handling routines during the initialization, which
   2914 the old functions do not.  The functions png_read_destroy() and
   2915 png_write_destroy() do not actually free the memory that libpng
   2916 allocated for these structs, but just reset the data structures, so they
   2917 can be used instead of png_destroy_read_struct() and
   2918 png_destroy_write_struct() if you feel there is too much system overhead
   2919 allocating and freeing the png_struct for each image read.
   2920 
   2921 Setting the error callbacks via png_set_message_fn() before
   2922 png_read_init() as was suggested in libpng-0.88 is no longer supported
   2923 because this caused applications that do not use custom error functions
   2924 to fail if the png_ptr was not initialized to zero.  It is still possible
   2925 to set the error callbacks AFTER png_read_init(), or to change them with
   2926 png_set_error_fn(), which is essentially the same function, but with a new
   2927 name to force compilation errors with applications that try to use the old
   2928 method.
   2929 
   2930 Starting with version 1.0.7, you can find out which version of the library
   2931 you are using at run-time:
   2932 
   2933    png_uint_32 libpng_vn = png_access_version_number();
   2934 
   2935 The number libpng_vn is constructed from the major version, minor
   2936 version with leading zero, and release number with leading zero,
   2937 (e.g., libpng_vn for version 1.0.7 is 10007).
   2938 
   2939 You can also check which version of png.h you used when compiling your
   2940 application:
   2941 
   2942    png_uint_32 application_vn = PNG_LIBPNG_VER;
   2943 
   2944 VIII.  Changes to Libpng from version 1.0.x to 1.2.x
   2945 
   2946 Support for user memory management was enabled by default.  To
   2947 accomplish this, the functions png_create_read_struct_2(),
   2948 png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
   2949 png_malloc_default(), and png_free_default() were added.
   2950 
   2951 Support for the iTXt chunk has been enabled by default as of
   2952 version 1.2.41.
   2953 
   2954 Support for certain MNG features was enabled.
   2955 
   2956 Support for numbered error messages was added.  However, we never got
   2957 around to actually numbering the error messages.  The function
   2958 png_set_strip_error_numbers() was added (Note: the prototype for this
   2959 function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
   2960 builds of libpng-1.2.15.  It was restored in libpng-1.2.36).
   2961 
   2962 The png_malloc_warn() function was added at libpng-1.2.3.  This issues
   2963 a png_warning and returns NULL instead of aborting when it fails to
   2964 acquire the requested memory allocation.
   2965 
   2966 Support for setting user limits on image width and height was enabled
   2967 by default.  The functions png_set_user_limits(), png_get_user_width_max(),
   2968 and png_get_user_height_max() were added at libpng-1.2.6.
   2969 
   2970 The png_set_add_alpha() function was added at libpng-1.2.7.
   2971 
   2972 The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
   2973 Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
   2974 tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
   2975 deprecated.
   2976 
   2977 A number of macro definitions in support of runtime selection of
   2978 assembler code features (especially Intel MMX code support) were
   2979 added at libpng-1.2.0:
   2980 
   2981     PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
   2982     PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
   2983     PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
   2984     PNG_ASM_FLAG_MMX_READ_INTERLACE
   2985     PNG_ASM_FLAG_MMX_READ_FILTER_SUB
   2986     PNG_ASM_FLAG_MMX_READ_FILTER_UP
   2987     PNG_ASM_FLAG_MMX_READ_FILTER_AVG
   2988     PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
   2989     PNG_ASM_FLAGS_INITIALIZED
   2990     PNG_MMX_READ_FLAGS
   2991     PNG_MMX_FLAGS
   2992     PNG_MMX_WRITE_FLAGS
   2993     PNG_MMX_FLAGS
   2994 
   2995 We added the following functions in support of runtime
   2996 selection of assembler code features:
   2997 
   2998     png_get_mmx_flagmask()
   2999     png_set_mmx_thresholds()
   3000     png_get_asm_flags()
   3001     png_get_mmx_bitdepth_threshold()
   3002     png_get_mmx_rowbytes_threshold()
   3003     png_set_asm_flags()
   3004 
   3005 We replaced all of these functions with simple stubs in libpng-1.2.20,
   3006 when the Intel assembler code was removed due to a licensing issue.
   3007 
   3008 These macros are deprecated:
   3009 
   3010     PNG_READ_TRANSFORMS_NOT_SUPPORTED
   3011     PNG_PROGRESSIVE_READ_NOT_SUPPORTED
   3012     PNG_NO_SEQUENTIAL_READ_SUPPORTED
   3013     PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
   3014     PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
   3015     PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
   3016 
   3017 They have been replaced, respectively, by:
   3018 
   3019     PNG_NO_READ_TRANSFORMS
   3020     PNG_NO_PROGRESSIVE_READ
   3021     PNG_NO_SEQUENTIAL_READ
   3022     PNG_NO_WRITE_TRANSFORMS
   3023     PNG_NO_READ_ANCILLARY_CHUNKS
   3024     PNG_NO_WRITE_ANCILLARY_CHUNKS
   3025 
   3026 PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been
   3027 deprecated since libpng-1.0.16 and libpng-1.2.6.
   3028 
   3029 The function
   3030     png_check_sig(sig, num)
   3031 was replaced with
   3032     !png_sig_cmp(sig, 0, num)
   3033 It has been deprecated since libpng-0.90.
   3034 
   3035 The function
   3036     png_set_gray_1_2_4_to_8()
   3037 which also expands tRNS to alpha was replaced with
   3038     png_set_expand_gray_1_2_4_to_8()
   3039 which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
   3040 
   3041 IX.  (Omitted)
   3042 
   3043 
   3044 X. Detecting libpng
   3045 
   3046 The png_get_io_ptr() function has been present since libpng-0.88, has never
   3047 changed, and is unaffected by conditional compilation macros.  It is the
   3048 best choice for use in configure scripts for detecting the presence of any
   3049 libpng version since 0.88.  In an autoconf "configure.in" you could use
   3050 
   3051     AC_CHECK_LIB(png, png_get_io_ptr, ...
   3052 
   3053 XI. Source code repository
   3054 
   3055 Since about February 2009, version 1.2.34, libpng has been under "git" source
   3056 control.  The git repository was built from old libpng-x.y.z.tar.gz files
   3057 going back to version 0.70.  You can access the git repository (read only)
   3058 at
   3059 
   3060     git://libpng.git.sourceforge.net/gitroot/libpng
   3061 
   3062 or you can browse it via "gitweb" at
   3063 
   3064     http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
   3065 
   3066 Patches can be sent to glennrp at users.sourceforge.net or to
   3067 png-mng-implement at lists.sourceforge.net or you can upload them to
   3068 the libpng bug tracker at
   3069 
   3070     http://libpng.sourceforge.net
   3071 
   3072 XII. Coding style
   3073 
   3074 Our coding style is similar to the "Allman" style, with curly
   3075 braces on separate lines:
   3076 
   3077     if (condition)
   3078     {
   3079        action;
   3080     }
   3081 
   3082     else if (another condition)
   3083     {
   3084        another action;
   3085     }
   3086 
   3087 The braces can be omitted from simple one-line actions:
   3088 
   3089     if (condition)
   3090        return (0);
   3091 
   3092 We use 3-space indentation, except for continued statements which
   3093 are usually indented the same as the first line of the statement
   3094 plus four more spaces.
   3095 
   3096 For macro definitions we use 2-space indentation, always leaving the "#"
   3097 in the first column.
   3098 
   3099     #ifndef PNG_NO_FEATURE
   3100     #  ifndef PNG_FEATURE_SUPPORTED
   3101     #    define PNG_FEATURE_SUPPORTED
   3102     #  endif
   3103     #endif
   3104 
   3105 Comments appear with the leading "/*" at the same indentation as
   3106 the statement that follows the comment:
   3107 
   3108     /* Single-line comment */
   3109     statement;
   3110 
   3111     /* Multiple-line
   3112      * comment
   3113      */
   3114     statement;
   3115 
   3116 Very short comments can be placed at the end of the statement
   3117 to which they pertain:
   3118 
   3119     statement;    /* comment */
   3120 
   3121 We don't use C++ style ("//") comments. We have, however,
   3122 used them in the past in some now-abandoned MMX assembler
   3123 code.
   3124 
   3125 Functions and their curly braces are not indented, and
   3126 exported functions are marked with PNGAPI:
   3127 
   3128  /* This is a public function that is visible to
   3129   * application programers. It does thus-and-so.
   3130   */
   3131  void PNGAPI
   3132  png_exported_function(png_ptr, png_info, foo)
   3133  {
   3134     body;
   3135  }
   3136 
   3137 The prototypes for all exported functions appear in png.h,
   3138 above the comment that says
   3139 
   3140     /* Maintainer: Put new public prototypes here ... */
   3141 
   3142 We mark all non-exported functions with "/* PRIVATE */"":
   3143 
   3144  void /* PRIVATE */
   3145  png_non_exported_function(png_ptr, png_info, foo)
   3146  {
   3147     body;
   3148  }
   3149 
   3150 The prototypes for non-exported functions (except for those in
   3151 pngtest) appear in
   3152 the PNG_INTERNAL section of png.h
   3153 above the comment that says
   3154 
   3155   /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */
   3156 
   3157 The names of all exported functions and variables begin
   3158 with  "png_", and all publicly visible C preprocessor
   3159 macros begin with "PNG_".
   3160 
   3161 We put a space after each comma and after each semicolon
   3162 in "for" statments, and we put spaces before and after each
   3163 C binary operator and after "for" or "while".  We don't
   3164 put a space between a typecast and the expression being
   3165 cast, nor do we put one between a function name and the
   3166 left parenthesis that follows it:
   3167 
   3168     for (i = 2; i > 0; --i)
   3169        y[i] = a(x) + (int)b;
   3170 
   3171 We prefer #ifdef and #ifndef to #if defined() and if !defined()
   3172 when there is only one macro being tested.
   3173 
   3174 We do not use the TAB character for indentation in the C sources.
   3175 
   3176 Lines do not exceed 80 characters.
   3177 
   3178 Other rules can be inferred by inspecting the libpng source.
   3179 
   3180 XIII. Y2K Compliance in libpng
   3181 
   3182 July 9, 2011
   3183 
   3184 Since the PNG Development group is an ad-hoc body, we can't make
   3185 an official declaration.
   3186 
   3187 This is your unofficial assurance that libpng from version 0.71 and
   3188 upward through 1.2.46 are Y2K compliant.  It is my belief that earlier
   3189 versions were also Y2K compliant.
   3190 
   3191 Libpng only has three year fields.  One is a 2-byte unsigned integer that
   3192 will hold years up to 65535.  The other two hold the date in text
   3193 format, and will hold years up to 9999.
   3194 
   3195 The integer is
   3196     "png_uint_16 year" in png_time_struct.
   3197 
   3198 The strings are
   3199     "png_charp time_buffer" in png_struct and
   3200     "near_time_buffer", which is a local character string in png.c.
   3201 
   3202 There are seven time-related functions:
   3203 
   3204     png_convert_to_rfc_1123() in png.c
   3205       (formerly png_convert_to_rfc_1152() in error)
   3206     png_convert_from_struct_tm() in pngwrite.c, called
   3207       in pngwrite.c
   3208     png_convert_from_time_t() in pngwrite.c
   3209     png_get_tIME() in pngget.c
   3210     png_handle_tIME() in pngrutil.c, called in pngread.c
   3211     png_set_tIME() in pngset.c
   3212     png_write_tIME() in pngwutil.c, called in pngwrite.c
   3213 
   3214 All appear to handle dates properly in a Y2K environment.  The
   3215 png_convert_from_time_t() function calls gmtime() to convert from system
   3216 clock time, which returns (year - 1900), which we properly convert to
   3217 the full 4-digit year.  There is a possibility that applications using
   3218 libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
   3219 function, or that they are incorrectly passing only a 2-digit year
   3220 instead of "year - 1900" into the png_convert_from_struct_tm() function,
   3221 but this is not under our control.  The libpng documentation has always
   3222 stated that it works with 4-digit years, and the APIs have been
   3223 documented as such.
   3224 
   3225 The tIME chunk itself is also Y2K compliant.  It uses a 2-byte unsigned
   3226 integer to hold the year, and can hold years as large as 65535.
   3227 
   3228 zlib, upon which libpng depends, is also Y2K compliant.  It contains
   3229 no date-related code.
   3230 
   3231 
   3232    Glenn Randers-Pehrson
   3233    libpng maintainer
   3234    PNG Development Group
   3235