• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1libpng-manual.txt - A description on how to use and modify libpng
2
3 Copyright (c) 2018-2019 Cosmin Truta
4 Copyright (c) 1998-2018 Glenn Randers-Pehrson
5
6 This document is released under the libpng license.
7 For conditions of distribution and use, see the disclaimer
8 and license in png.h
9
10 Based on:
11
12 libpng version 1.6.36, December 2018, through 1.6.37 - April 2019
13 Updated and distributed by Cosmin Truta
14 Copyright (c) 2018-2019 Cosmin Truta
15
16 libpng versions 0.97, January 1998, through 1.6.35 - July 2018
17 Updated and distributed by Glenn Randers-Pehrson
18 Copyright (c) 1998-2018 Glenn Randers-Pehrson
19
20 libpng 1.0 beta 6 - version 0.96 - May 28, 1997
21 Updated and distributed by Andreas Dilger
22 Copyright (c) 1996, 1997 Andreas Dilger
23
24 libpng 1.0 beta 2 - version 0.88 - January 26, 1996
25 For conditions of distribution and use, see copyright
26 notice in png.h. Copyright (c) 1995, 1996 Guy Eric
27 Schalnat, Group 42, Inc.
28
29 Updated/rewritten per request in the libpng FAQ
30 Copyright (c) 1995, 1996 Frank J. T. Wojcik
31 December 18, 1995 & January 20, 1996
32
33 TABLE OF CONTENTS
34
35    I. Introduction
36   II. Structures
37  III. Reading
38   IV. Writing
39    V. Simplified API
40   VI. Modifying/Customizing libpng
41  VII. MNG support
42 VIII. Changes to Libpng from version 0.88
43   IX. Changes to Libpng from version 1.0.x to 1.2.x
44    X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
45   XI. Changes to Libpng from version 1.4.x to 1.5.x
46  XII. Changes to Libpng from version 1.5.x to 1.6.x
47 XIII. Detecting libpng
48  XIV. Source code repository
49   XV. Coding style
50
51I. Introduction
52
53This file describes how to use and modify the PNG reference library
54(known as libpng) for your own use.  In addition to this
55file, example.c is a good starting point for using the library, as
56it is heavily commented and should include everything most people
57will need.  We assume that libpng is already installed; see the
58INSTALL file for instructions on how to configure and install libpng.
59
60For examples of libpng usage, see the files "example.c", "pngtest.c",
61and the files in the "contrib" directory, all of which are included in
62the libpng distribution.
63
64Libpng was written as a companion to the PNG specification, as a way
65of reducing the amount of time and effort it takes to support the PNG
66file format in application programs.
67
68The PNG specification (second edition), November 2003, is available as
69a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at
70<https://www.w3.org/TR/2003/REC-PNG-20031110/>.
71The W3C and ISO documents have identical technical content.
72
73The PNG-1.2 specification is available at
74<https://png-mng.sourceforge.io/pub/png/spec/1.2/>.
75It is technically equivalent
76to the PNG specification (second edition) but has some additional material.
77
78The PNG-1.0 specification is available as RFC 2083 at
79<https://png-mng.sourceforge.io/pub/png/spec/1.0/> and as a
80W3C Recommendation at <https://www.w3.org/TR/REC-png-961001>.
81
82Some additional chunks are described in the special-purpose public chunks
83documents at <http://www.libpng.org/pub/png/spec/register/>
84
85Other information
86about PNG, and the latest version of libpng, can be found at the PNG home
87page, <http://www.libpng.org/pub/png/>.
88
89Most users will not have to modify the library significantly; advanced
90users may want to modify it more.  All attempts were made to make it as
91complete as possible, while keeping the code easy to understand.
92Currently, this library only supports C.  Support for other languages
93is being considered.
94
95Libpng has been designed to handle multiple sessions at one time,
96to be easily modifiable, to be portable to the vast majority of
97machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
98to use.  The ultimate goal of libpng is to promote the acceptance of
99the PNG file format in whatever way possible.  While there is still
100work to be done (see the TODO file), libpng should cover the
101majority of the needs of its users.
102
103Libpng uses zlib for its compression and decompression of PNG files.
104Further information about zlib, and the latest version of zlib, can
105be found at the zlib home page, <https://zlib.net/>.
106The zlib compression utility is a general purpose utility that is
107useful for more than PNG files, and can be used without libpng.
108See the documentation delivered with zlib for more details.
109You can usually find the source files for the zlib utility wherever you
110find the libpng source files.
111
112Libpng is thread safe, provided the threads are using different
113instances of the structures.  Each thread should have its own
114png_struct and png_info instances, and thus its own image.
115Libpng does not protect itself against two threads using the
116same instance of a structure.
117
118II. Structures
119
120There are two main structures that are important to libpng, png_struct
121and png_info.  Both are internal structures that are no longer exposed
122in the libpng interface (as of libpng 1.5.0).
123
124The png_info structure is designed to provide information about the
125PNG file.  At one time, the fields of png_info were intended to be
126directly accessible to the user.  However, this tended to cause problems
127with applications using dynamically loaded libraries, and as a result
128a set of interface functions for png_info (the png_get_*() and png_set_*()
129functions) was developed, and direct access to the png_info fields was
130deprecated..
131
132The png_struct structure is the object used by the library to decode a
133single image.  As of 1.5.0 this structure is also not exposed.
134
135Almost all libpng APIs require a pointer to a png_struct as the first argument.
136Many (in particular the png_set and png_get APIs) also require a pointer
137to png_info as the second argument.  Some application visible macros
138defined in png.h designed for basic data access (reading and writing
139integers in the PNG format) don't take a png_info pointer, but it's almost
140always safe to assume that a (png_struct*) has to be passed to call an API
141function.
142
143You can have more than one png_info structure associated with an image,
144as illustrated in pngtest.c, one for information valid prior to the
145IDAT chunks and another (called "end_info" below) for things after them.
146
147The png.h header file is an invaluable reference for programming with libpng.
148And while I'm on the topic, make sure you include the libpng header file:
149
150#include <png.h>
151
152and also (as of libpng-1.5.0) the zlib header file, if you need it:
153
154#include <zlib.h>
155
156Types
157
158The png.h header file defines a number of integral types used by the
159APIs.  Most of these are fairly obvious; for example types corresponding
160to integers of particular sizes and types for passing color values.
161
162One exception is how non-integral numbers are handled.  For application
163convenience most APIs that take such numbers have C (double) arguments;
164however, internally PNG, and libpng, use 32 bit signed integers and encode
165the value by multiplying by 100,000.  As of libpng 1.5.0 a convenience
166macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
167which is simply (png_int_32).
168
169All APIs that take (double) arguments also have a matching API that
170takes the corresponding fixed point integer arguments.  The fixed point
171API has the same name as the floating point one with "_fixed" appended.
172The actual range of values permitted in the APIs is frequently less than
173the full range of (png_fixed_point) (-21474 to +21474).  When APIs require
174a non-negative argument the type is recorded as png_uint_32 above.  Consult
175the header file and the text below for more information.
176
177Special care must be take with sCAL chunk handling because the chunk itself
178uses non-integral values encoded as strings containing decimal floating point
179numbers.  See the comments in the header file.
180
181Configuration
182
183The main header file function declarations are frequently protected by C
184preprocessing directives of the form:
185
186    #ifdef PNG_feature_SUPPORTED
187    declare-function
188    #endif
189    ...
190    #ifdef PNG_feature_SUPPORTED
191    use-function
192    #endif
193
194The library can be built without support for these APIs, although a
195standard build will have all implemented APIs.  Application programs
196should check the feature macros before using an API for maximum
197portability.  From libpng 1.5.0 the feature macros set during the build
198of libpng are recorded in the header file "pnglibconf.h" and this file
199is always included by png.h.
200
201If you don't need to change the library configuration from the default, skip to
202the next section ("Reading").
203
204Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
205of the build project files in the 'projects' directory simply copy
206scripts/pnglibconf.h.prebuilt to pnglibconf.h.  This means that these build
207systems do not permit easy auto-configuration of the library - they only
208support the default configuration.
209
210The easiest way to make minor changes to the libpng configuration when
211auto-configuration is supported is to add definitions to the command line
212using (typically) CPPFLAGS.  For example:
213
214CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
215
216will change the internal libpng math implementation for gamma correction and
217other arithmetic calculations to fixed point, avoiding the need for fast
218floating point support.  The result can be seen in the generated pnglibconf.h -
219make sure it contains the changed feature macro setting.
220
221If you need to make more extensive configuration changes - more than one or two
222feature macro settings - you can either add -DPNG_USER_CONFIG to the build
223command line and put a list of feature macro settings in pngusr.h or you can set
224DFA_XTRA (a makefile variable) to a file containing the same information in the
225form of 'option' settings.
226
227A. Changing pnglibconf.h
228
229A variety of methods exist to build libpng.  Not all of these support
230reconfiguration of pnglibconf.h.  To reconfigure pnglibconf.h it must either be
231rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
232
233Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
234pnglibconf.h and changing the lines defining the supported features, paying
235very close attention to the 'option' information in scripts/pnglibconf.dfa
236that describes those features and their requirements.  This is easy to get
237wrong.
238
239B. Configuration using DFA_XTRA
240
241Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
242variant such as 'nawk' or 'gawk', is available.  The configure build will
243automatically find an appropriate awk and build pnglibconf.h.
244The scripts/pnglibconf.mak file contains a set of make rules for doing the
245same thing if configure is not used, and many of the makefiles in the scripts
246directory use this approach.
247
248When rebuilding simply write a new file containing changed options and set
249DFA_XTRA to the name of this file.  This causes the build to append the new file
250to the end of scripts/pnglibconf.dfa.  The pngusr.dfa file should contain lines
251of the following forms:
252
253everything = off
254
255This turns all optional features off.  Include it at the start of pngusr.dfa to
256make it easier to build a minimal configuration.  You will need to turn at least
257some features on afterward to enable either reading or writing code, or both.
258
259option feature on
260option feature off
261
262Enable or disable a single feature.  This will automatically enable other
263features required by a feature that is turned on or disable other features that
264require a feature which is turned off.  Conflicting settings will cause an error
265message to be emitted by awk.
266
267setting feature default value
268
269Changes the default value of setting 'feature' to 'value'.  There are a small
270number of settings listed at the top of pnglibconf.h, they are documented in the
271source code.  Most of these values have performance implications for the library
272but most of them have no visible effect on the API.  Some can also be overridden
273from the API.
274
275This method of building a customized pnglibconf.h is illustrated in
276contrib/pngminim/*.  See the "$(PNGCONF):" target in the makefile and
277pngusr.dfa in these directories.
278
279C. Configuration using PNG_USER_CONFIG
280
281If -DPNG_USER_CONFIG is added to the CPPFLAGS when pnglibconf.h is built,
282the file pngusr.h will automatically be included before the options in
283scripts/pnglibconf.dfa are processed.  Your pngusr.h file should contain only
284macro definitions turning features on or off or setting settings.
285
286Apart from the global setting "everything = off" all the options listed above
287can be set using macros in pngusr.h:
288
289#define PNG_feature_SUPPORTED
290
291is equivalent to:
292
293option feature on
294
295#define PNG_NO_feature
296
297is equivalent to:
298
299option feature off
300
301#define PNG_feature value
302
303is equivalent to:
304
305setting feature default value
306
307Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
308pngusr file you supply override the contents of scripts/pnglibconf.dfa
309
310If confusing or incomprehensible behavior results it is possible to
311examine the intermediate file pnglibconf.dfn to find the full set of
312dependency information for each setting and option.  Simply locate the
313feature in the file and read the C comments that precede it.
314
315This method is also illustrated in the contrib/pngminim/* makefiles and
316pngusr.h.
317
318III. Reading
319
320We'll now walk you through the possible functions to call when reading
321in a PNG file sequentially, briefly explaining the syntax and purpose
322of each one.  See example.c and png.h for more detail.  While
323progressive reading is covered in the next section, you will still
324need some of the functions discussed in this section to read a PNG
325file.
326
327Setup
328
329You will want to do the I/O initialization(*) before you get into libpng,
330so if it doesn't work, you don't have much to undo.  Of course, you
331will also want to insure that you are, in fact, dealing with a PNG
332file.  Libpng provides a simple check to see if a file is a PNG file.
333To use it, pass in the first 1 to 8 bytes of the file to the function
334png_sig_cmp(), and it will return 0 (false) if the bytes match the
335corresponding bytes of the PNG signature, or nonzero (true) otherwise.
336Of course, the more bytes you pass in, the greater the accuracy of the
337prediction.
338
339If you are intending to keep the file pointer open for use in libpng,
340you must ensure you don't read more than 8 bytes from the beginning
341of the file, and you also have to make a call to png_set_sig_bytes()
342with the number of bytes you read from the beginning.  Libpng will
343then only check the bytes (if any) that your program didn't read.
344
345(*): If you are not using the standard I/O functions, you will need
346to replace them with custom functions.  See the discussion under
347Customizing libpng.
348
349    FILE *fp = fopen(file_name, "rb");
350    if (!fp)
351    {
352       return ERROR;
353    }
354
355    if (fread(header, 1, number, fp) != number)
356    {
357       return ERROR;
358    }
359
360    is_png = !png_sig_cmp(header, 0, number);
361    if (!is_png)
362    {
363       return NOT_PNG;
364    }
365
366Next, png_struct and png_info need to be allocated and initialized.  In
367order to ensure that the size of these structures is correct even with a
368dynamically linked libpng, there are functions to initialize and
369allocate the structures.  We also pass the library version, optional
370pointers to error handling functions, and a pointer to a data struct for
371use by the error functions, if necessary (the pointer and functions can
372be NULL if the default error handlers are to be used).  See the section
373on Changes to Libpng below regarding the old initialization functions.
374The structure allocation functions quietly return NULL if they fail to
375create the structure, so your application should check for that.
376
377    png_structp png_ptr = png_create_read_struct
378        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
379        user_error_fn, user_warning_fn);
380
381    if (!png_ptr)
382       return ERROR;
383
384    png_infop info_ptr = png_create_info_struct(png_ptr);
385
386    if (!info_ptr)
387    {
388       png_destroy_read_struct(&png_ptr,
389           (png_infopp)NULL, (png_infopp)NULL);
390       return ERROR;
391    }
392
393If you want to use your own memory allocation routines,
394use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
395png_create_read_struct_2() instead of png_create_read_struct():
396
397    png_structp png_ptr = png_create_read_struct_2
398        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
399        user_error_fn, user_warning_fn, (png_voidp)
400        user_mem_ptr, user_malloc_fn, user_free_fn);
401
402The error handling routines passed to png_create_read_struct()
403and the memory alloc/free routines passed to png_create_struct_2()
404are only necessary if you are not using the libpng supplied error
405handling and memory alloc/free functions.
406
407When libpng encounters an error, it expects to longjmp back
408to your routine.  Therefore, you will need to call setjmp and pass
409your png_jmpbuf(png_ptr).  If you read the file from different
410routines, you will need to update the longjmp buffer every time you enter
411a new routine that will call a png_*() function.
412
413See your documentation of setjmp/longjmp for your compiler for more
414information on setjmp/longjmp.  See the discussion on libpng error
415handling in the Customizing Libpng section below for more information
416on the libpng error handling.  If an error occurs, and libpng longjmp's
417back to your setjmp, you will want to call png_destroy_read_struct() to
418free any memory.
419
420    if (setjmp(png_jmpbuf(png_ptr)))
421    {
422       png_destroy_read_struct(&png_ptr, &info_ptr,
423           &end_info);
424       fclose(fp);
425       return ERROR;
426    }
427
428Pass (png_infopp)NULL instead of &end_info if you didn't create
429an end_info structure.
430
431If you would rather avoid the complexity of setjmp/longjmp issues,
432you can compile libpng with PNG_NO_SETJMP, in which case
433errors will result in a call to PNG_ABORT() which defaults to abort().
434
435You can #define PNG_ABORT() to a function that does something
436more useful than abort(), as long as your function does not
437return.
438
439Now you need to set up the input code.  The default for libpng is to
440use the C function fread().  If you use this, you will need to pass a
441valid FILE * in the function png_init_io().  Be sure that the file is
442opened in binary mode.  If you wish to handle reading data in another
443way, you need not call the png_init_io() function, but you must then
444implement the libpng I/O methods discussed in the Customizing Libpng
445section below.
446
447    png_init_io(png_ptr, fp);
448
449If you had previously opened the file and read any of the signature from
450the beginning in order to see if this was a PNG file, you need to let
451libpng know that there are some bytes missing from the start of the file.
452
453    png_set_sig_bytes(png_ptr, number);
454
455You can change the zlib compression buffer size to be used while
456reading compressed data with
457
458    png_set_compression_buffer_size(png_ptr, buffer_size);
459
460where the default size is 8192 bytes.  Note that the buffer size
461is changed immediately and the buffer is reallocated immediately,
462instead of setting a flag to be acted upon later.
463
464If you want CRC errors to be handled in a different manner than
465the default, use
466
467    png_set_crc_action(png_ptr, crit_action, ancil_action);
468
469The values for png_set_crc_action() say how libpng is to handle CRC errors in
470ancillary and critical chunks, and whether to use the data contained
471therein. Starting with libpng-1.6.26, this also governs how an ADLER32 error
472is handled while reading the IDAT chunk. Note that it is impossible to
473"discard" data in a critical chunk.
474
475Choices for (int) crit_action are
476   PNG_CRC_DEFAULT      0  error/quit
477   PNG_CRC_ERROR_QUIT   1  error/quit
478   PNG_CRC_WARN_USE     3  warn/use data
479   PNG_CRC_QUIET_USE    4  quiet/use data
480   PNG_CRC_NO_CHANGE    5  use the current value
481
482Choices for (int) ancil_action are
483   PNG_CRC_DEFAULT      0  error/quit
484   PNG_CRC_ERROR_QUIT   1  error/quit
485   PNG_CRC_WARN_DISCARD 2  warn/discard data
486   PNG_CRC_WARN_USE     3  warn/use data
487   PNG_CRC_QUIET_USE    4  quiet/use data
488   PNG_CRC_NO_CHANGE    5  use the current value
489
490When the setting for crit_action is PNG_CRC_QUIET_USE, the CRC and ADLER32
491checksums are not only ignored, but they are not evaluated.
492
493Setting up callback code
494
495You can set up a callback function to handle any unknown chunks in the
496input stream. You must supply the function
497
498    read_chunk_callback(png_structp png_ptr,
499         png_unknown_chunkp chunk);
500    {
501       /* The unknown chunk structure contains your
502          chunk data, along with similar data for any other
503          unknown chunks: */
504
505           png_byte name[5];
506           png_byte *data;
507           size_t size;
508
509       /* Note that libpng has already taken care of
510          the CRC handling */
511
512       /* put your code here.  Search for your chunk in the
513          unknown chunk structure, process it, and return one
514          of the following: */
515
516       return -n; /* chunk had an error */
517       return 0; /* did not recognize */
518       return n; /* success */
519    }
520
521(You can give your function another name that you like instead of
522"read_chunk_callback")
523
524To inform libpng about your function, use
525
526    png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
527        read_chunk_callback);
528
529This names not only the callback function, but also a user pointer that
530you can retrieve with
531
532    png_get_user_chunk_ptr(png_ptr);
533
534If you call the png_set_read_user_chunk_fn() function, then all unknown
535chunks which the callback does not handle will be saved when read.  You can
536cause them to be discarded by returning '1' ("handled") instead of '0'.  This
537behavior will change in libpng 1.7 and the default handling set by the
538png_set_keep_unknown_chunks() function, described below, will be used when the
539callback returns 0.  If you want the existing behavior you should set the global
540default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current
541versions of libpng and with 1.7.  Libpng 1.6 issues a warning if you keep the
542default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0.
543
544At this point, you can set up a callback function that will be
545called after each row has been read, which you can use to control
546a progress meter or the like.  It's demonstrated in pngtest.c.
547You must supply a function
548
549    void read_row_callback(png_structp png_ptr,
550       png_uint_32 row, int pass);
551    {
552      /* put your code here */
553    }
554
555(You can give it another name that you like instead of "read_row_callback")
556
557To inform libpng about your function, use
558
559    png_set_read_status_fn(png_ptr, read_row_callback);
560
561When this function is called the row has already been completely processed and
562the 'row' and 'pass' refer to the next row to be handled.  For the
563non-interlaced case the row that was just handled is simply one less than the
564passed in row number, and pass will always be 0.  For the interlaced case the
565same applies unless the row value is 0, in which case the row just handled was
566the last one from one of the preceding passes.  Because interlacing may skip a
567pass you cannot be sure that the preceding pass is just 'pass-1'; if you really
568need to know what the last pass is record (row,pass) from the callback and use
569the last recorded value each time.
570
571As with the user transform you can find the output row using the
572PNG_ROW_FROM_PASS_ROW macro.
573
574Unknown-chunk handling
575
576Now you get to set the way the library processes unknown chunks in the
577input PNG stream. Both known and unknown chunks will be read.  Normal
578behavior is that known chunks will be parsed into information in
579various info_ptr members while unknown chunks will be discarded. This
580behavior can be wasteful if your application will never use some known
581chunk types. To change this, you can call:
582
583    png_set_keep_unknown_chunks(png_ptr, keep,
584        chunk_list, num_chunks);
585
586    keep       - 0: default unknown chunk handling
587                 1: ignore; do not keep
588                 2: keep only if safe-to-copy
589                 3: keep even if unsafe-to-copy
590
591               You can use these definitions:
592                 PNG_HANDLE_CHUNK_AS_DEFAULT   0
593                 PNG_HANDLE_CHUNK_NEVER        1
594                 PNG_HANDLE_CHUNK_IF_SAFE      2
595                 PNG_HANDLE_CHUNK_ALWAYS       3
596
597    chunk_list - list of chunks affected (a byte string,
598                 five bytes per chunk, NULL or '\0' if
599                 num_chunks is positive; ignored if
600                 numchunks <= 0).
601
602    num_chunks - number of chunks affected; if 0, all
603                 unknown chunks are affected.  If positive,
604                 only the chunks in the list are affected,
605                 and if negative all unknown chunks and
606                 all known chunks except for the IHDR,
607                 PLTE, tRNS, IDAT, and IEND chunks are
608                 affected.
609
610Unknown chunks declared in this way will be saved as raw data onto a
611list of png_unknown_chunk structures.  If a chunk that is normally
612known to libpng is named in the list, it will be handled as unknown,
613according to the "keep" directive.  If a chunk is named in successive
614instances of png_set_keep_unknown_chunks(), the final instance will
615take precedence.  The IHDR and IEND chunks should not be named in
616chunk_list; if they are, libpng will process them normally anyway.
617If you know that your application will never make use of some particular
618chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
619
620Here is an example of the usage of png_set_keep_unknown_chunks(),
621where the private "vpAg" chunk will later be processed by a user chunk
622callback function:
623
624    png_byte vpAg[5]={118, 112,  65, 103, (png_byte) '\0'};
625
626    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
627      png_byte unused_chunks[]=
628      {
629        104,  73,  83,  84, (png_byte) '\0',   /* hIST */
630        105,  84,  88, 116, (png_byte) '\0',   /* iTXt */
631        112,  67,  65,  76, (png_byte) '\0',   /* pCAL */
632        115,  67,  65,  76, (png_byte) '\0',   /* sCAL */
633        115,  80,  76,  84, (png_byte) '\0',   /* sPLT */
634        116,  73,  77,  69, (png_byte) '\0',   /* tIME */
635      };
636    #endif
637
638    ...
639
640    #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
641      /* ignore all unknown chunks
642       * (use global setting "2" for libpng16 and earlier):
643       */
644      png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0);
645
646      /* except for vpAg: */
647      png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
648
649      /* also ignore unused known chunks: */
650      png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
651         (int)(sizeof unused_chunks)/5);
652    #endif
653
654User limits
655
656The PNG specification allows the width and height of an image to be as
657large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
658For safety, libpng imposes a default limit of 1 million rows and columns.
659Larger images will be rejected immediately with a png_error() call. If
660you wish to change these limits, you can use
661
662   png_set_user_limits(png_ptr, width_max, height_max);
663
664to set your own limits (libpng may reject some very wide images
665anyway because of potential buffer overflow conditions).
666
667You should put this statement after you create the PNG structure and
668before calling png_read_info(), png_read_png(), or png_process_data().
669
670When writing a PNG datastream, put this statement before calling
671png_write_info() or png_write_png().
672
673If you need to retrieve the limits that are being applied, use
674
675   width_max = png_get_user_width_max(png_ptr);
676   height_max = png_get_user_height_max(png_ptr);
677
678The PNG specification sets no limit on the number of ancillary chunks
679allowed in a PNG datastream.  By default, libpng imposes a limit of
680a total of 1000 sPLT, tEXt, iTXt, zTXt, and unknown chunks to be stored.
681If you have set up both info_ptr and end_info_ptr, the limit applies
682separately to each.  You can change the limit on the total number of such
683chunks that will be stored, with
684
685   png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
686
687where 0x7fffffffL means unlimited.  You can retrieve this limit with
688
689   chunk_cache_max = png_get_chunk_cache_max(png_ptr);
690
691Libpng imposes a limit of 8 Megabytes (8,000,000 bytes) on the amount of
692memory that any chunk other than IDAT can occupy, originally or when
693decompressed (prior to libpng-1.6.32 the limit was only applied to compressed
694chunks after decompression). You can change this limit with
695
696   png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
697
698and you can retrieve the limit with
699
700   chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
701
702Any chunks that would cause either of these limits to be exceeded will
703be ignored.
704
705Information about your system
706
707If you intend to display the PNG or to incorporate it in other image data you
708need to tell libpng information about your display or drawing surface so that
709libpng can convert the values in the image to match the display.
710
711From libpng-1.5.4 this information can be set before reading the PNG file
712header.  In earlier versions png_set_gamma() existed but behaved incorrectly if
713called before the PNG file header had been read and png_set_alpha_mode() did not
714exist.
715
716If you need to support versions prior to libpng-1.5.4 test the version number
717as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
718described in the appropriate manual page.
719
720You give libpng the encoding expected by your system expressed as a 'gamma'
721value.  You can also specify a default encoding for the PNG file in
722case the required information is missing from the file.  By default libpng
723assumes that the PNG data matches your system, to keep this default call:
724
725   png_set_gamma(png_ptr, screen_gamma, output_gamma);
726
727or you can use the fixed point equivalent:
728
729   png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma,
730      PNG_FP_1*output_gamma);
731
732If you don't know the gamma for your system it is probably 2.2 - a good
733approximation to the IEC standard for display systems (sRGB).  If images are
734too contrasty or washed out you got the value wrong - check your system
735documentation!
736
737Many systems permit the system gamma to be changed via a lookup table in the
738display driver, a few systems, including older Macs, change the response by
739default.  As of 1.5.4 three special values are available to handle common
740situations:
741
742   PNG_DEFAULT_sRGB: Indicates that the system conforms to the
743                     IEC 61966-2-1 standard.  This matches almost
744                     all systems.
745   PNG_GAMMA_MAC_18: Indicates that the system is an older
746                     (pre Mac OS 10.6) Apple Macintosh system with
747                     the default settings.
748   PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates
749                     that the system expects data with no gamma
750                     encoding.
751
752You would use the linear (unencoded) value if you need to process the pixel
753values further because this avoids the need to decode and re-encode each
754component value whenever arithmetic is performed.  A lot of graphics software
755uses linear values for this reason, often with higher precision component values
756to preserve overall accuracy.
757
758
759The output_gamma value expresses how to decode the output values, not how
760they are encoded.  The values used correspond to the normal numbers used to
761describe the overall gamma of a computer display system; for example 2.2 for
762an sRGB conformant system.  The values are scaled by 100000 in the _fixed
763version of the API (so 220000 for sRGB.)
764
765The inverse of the value is always used to provide a default for the PNG file
766encoding if it has no gAMA chunk and if png_set_gamma() has not been called
767to override the PNG gamma information.
768
769When the ALPHA_OPTIMIZED mode is selected the output gamma is used to encode
770opaque pixels however pixels with lower alpha values are not encoded,
771regardless of the output gamma setting.
772
773When the standard Porter Duff handling is requested with mode 1 the output
774encoding is set to be linear and the output_gamma value is only relevant
775as a default for input data that has no gamma information.  The linear output
776encoding will be overridden if png_set_gamma() is called - the results may be
777highly unexpected!
778
779The following numbers are derived from the sRGB standard and the research
780behind it.  sRGB is defined to be approximated by a PNG gAMA chunk value of
7810.45455 (1/2.2) for PNG.  The value implicitly includes any viewing
782correction required to take account of any differences in the color
783environment of the original scene and the intended display environment; the
784value expresses how to *decode* the image for display, not how the original
785data was *encoded*.
786
787sRGB provides a peg for the PNG standard by defining a viewing environment.
788sRGB itself, and earlier TV standards, actually use a more complex transform
789(a linear portion then a gamma 2.4 power law) than PNG can express.  (PNG is
790limited to simple power laws.)  By saying that an image for direct display on
791an sRGB conformant system should be stored with a gAMA chunk value of 45455
792(11.3.3.2 and 11.3.3.5 of the ISO PNG specification) the PNG specification
793makes it possible to derive values for other display systems and
794environments.
795
796The Mac value is deduced from the sRGB based on an assumption that the actual
797extra viewing correction used in early Mac display systems was implemented as
798a power 1.45 lookup table.
799
800Any system where a programmable lookup table is used or where the behavior of
801the final display device characteristics can be changed requires system
802specific code to obtain the current characteristic.  However this can be
803difficult and most PNG gamma correction only requires an approximate value.
804
805By default, if png_set_alpha_mode() is not called, libpng assumes that all
806values are unencoded, linear, values and that the output device also has a
807linear characteristic.  This is only very rarely correct - it is invariably
808better to call png_set_alpha_mode() with PNG_DEFAULT_sRGB than rely on the
809default if you don't know what the right answer is!
810
811The special value PNG_GAMMA_MAC_18 indicates an older Mac system (pre Mac OS
81210.6) which used a correction table to implement a somewhat lower gamma on an
813otherwise sRGB system.
814
815Both these values are reserved (not simple gamma values) in order to allow
816more precise correction internally in the future.
817
818NOTE: the values can be passed to either the fixed or floating
819point APIs, but the floating point API will also accept floating point
820values.
821
822The second thing you may need to tell libpng about is how your system handles
823alpha channel information.  Some, but not all, PNG files contain an alpha
824channel.  To display these files correctly you need to compose the data onto a
825suitable background, as described in the PNG specification.
826
827Libpng only supports composing onto a single color (using png_set_background;
828see below).  Otherwise you must do the composition yourself and, in this case,
829you may need to call png_set_alpha_mode:
830
831   #if PNG_LIBPNG_VER >= 10504
832      png_set_alpha_mode(png_ptr, mode, screen_gamma);
833   #else
834      png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
835   #endif
836
837The screen_gamma value is the same as the argument to png_set_gamma; however,
838how it affects the output depends on the mode.  png_set_alpha_mode() sets the
839file gamma default to 1/screen_gamma, so normally you don't need to call
840png_set_gamma.  If you need different defaults call png_set_gamma() before
841png_set_alpha_mode() - if you call it after it will override the settings made
842by png_set_alpha_mode().
843
844The mode is as follows:
845
846    PNG_ALPHA_PNG: The data is encoded according to the PNG
847specification.  Red, green and blue, or gray, components are
848gamma encoded color values and are not premultiplied by the
849alpha value.  The alpha value is a linear measure of the
850contribution of the pixel to the corresponding final output pixel.
851
852You should normally use this format if you intend to perform
853color correction on the color values; most, maybe all, color
854correction software has no handling for the alpha channel and,
855anyway, the math to handle pre-multiplied component values is
856unnecessarily complex.
857
858Before you do any arithmetic on the component values you need
859to remove the gamma encoding and multiply out the alpha
860channel.  See the PNG specification for more detail.  It is
861important to note that when an image with an alpha channel is
862scaled, linear encoded, pre-multiplied component values must
863be used!
864
865The remaining modes assume you don't need to do any further color correction or
866that if you do, your color correction software knows all about alpha (it
867probably doesn't!).  They 'associate' the alpha with the color information by
868storing color channel values that have been scaled by the alpha.  The
869advantage is that the color channels can be resampled (the image can be
870scaled) in this form.  The disadvantage is that normal practice is to store
871linear, not (gamma) encoded, values and this requires 16-bit channels for
872still images rather than the 8-bit channels that are just about sufficient if
873gamma encoding is used.  In addition all non-transparent pixel values,
874including completely opaque ones, must be gamma encoded to produce the final
875image.  These are the 'STANDARD', 'ASSOCIATED' or 'PREMULTIPLIED' modes
876described below (the latter being the two common names for associated alpha
877color channels). Note that PNG files always contain non-associated color
878channels; png_set_alpha_mode() with one of the modes causes the decoder to
879convert the pixels to an associated form before returning them to your
880application.
881
882Since it is not necessary to perform arithmetic on opaque color values so
883long as they are not to be resampled and are in the final color space it is
884possible to optimize the handling of alpha by storing the opaque pixels in
885the PNG format (adjusted for the output color space) while storing partially
886opaque pixels in the standard, linear, format.  The accuracy required for
887standard alpha composition is relatively low, because the pixels are
888isolated, therefore typically the accuracy loss in storing 8-bit linear
889values is acceptable.  (This is not true if the alpha channel is used to
890simulate transparency over large areas - use 16 bits or the PNG mode in
891this case!)  This is the 'OPTIMIZED' mode.  For this mode a pixel is
892treated as opaque only if the alpha value is equal to the maximum value.
893
894    PNG_ALPHA_STANDARD:  The data libpng produces is encoded in the
895standard way assumed by most correctly written graphics software.
896The gamma encoding will be removed by libpng and the
897linear component values will be pre-multiplied by the
898alpha channel.
899
900With this format the final image must be re-encoded to
901match the display gamma before the image is displayed.
902If your system doesn't do that, yet still seems to
903perform arithmetic on the pixels without decoding them,
904it is broken - check out the modes below.
905
906With PNG_ALPHA_STANDARD libpng always produces linear
907component values, whatever screen_gamma you supply.  The
908screen_gamma value is, however, used as a default for
909the file gamma if the PNG file has no gamma information.
910
911If you call png_set_gamma() after png_set_alpha_mode() you
912will override the linear encoding.  Instead the
913pre-multiplied pixel values will be gamma encoded but
914the alpha channel will still be linear.  This may
915actually match the requirements of some broken software,
916but it is unlikely.
917
918While linear 8-bit data is often used it has
919insufficient precision for any image with a reasonable
920dynamic range.  To avoid problems, and if your software
921supports it, use png_set_expand_16() to force all
922components to 16 bits.
923
924    PNG_ALPHA_OPTIMIZED: This mode is the same as PNG_ALPHA_STANDARD
925except that completely opaque pixels are gamma encoded according to
926the screen_gamma value.  Pixels with alpha less than 1.0
927will still have linear components.
928
929Use this format if you have control over your
930compositing software and so don't do other arithmetic
931(such as scaling) on the data you get from libpng.  Your
932compositing software can simply copy opaque pixels to
933the output but still has linear values for the
934non-opaque pixels.
935
936In normal compositing, where the alpha channel encodes
937partial pixel coverage (as opposed to broad area
938translucency), the inaccuracies of the 8-bit
939representation of non-opaque pixels are irrelevant.
940
941You can also try this format if your software is broken;
942it might look better.
943
944    PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD; however, all component
945values, including the alpha channel are gamma encoded.  This is
946broken because, in practice, no implementation that uses this choice
947correctly undoes the encoding before handling alpha composition.  Use this
948choice only if other serious errors in the software or hardware you use
949mandate it.  In most cases of broken software or hardware the bug in the
950final display manifests as a subtle halo around composited parts of the
951image.  You may not even perceive this as a halo; the composited part of
952the image may simply appear separate from the background, as though it had
953been cut out of paper and pasted on afterward.
954
955If you don't have to deal with bugs in software or hardware, or if you can fix
956them, there are three recommended ways of using png_set_alpha_mode():
957
958   png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
959       screen_gamma);
960
961You can do color correction on the result (libpng does not currently
962support color correction internally).  When you handle the alpha channel
963you need to undo the gamma encoding and multiply out the alpha.
964
965   png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
966       screen_gamma);
967   png_set_expand_16(png_ptr);
968
969If you are using the high level interface, don't call png_set_expand_16();
970instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
971
972With this mode you can't do color correction, but you can do arithmetic,
973including composition and scaling, on the data without further processing.
974
975   png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
976       screen_gamma);
977
978You can avoid the expansion to 16-bit components with this mode, but you
979lose the ability to scale the image or perform other linear arithmetic.
980All you can do is compose the result onto a matching output.  Since this
981mode is libpng-specific you also need to write your own composition
982software.
983
984The following are examples of calls to png_set_alpha_mode to achieve the
985required overall gamma correction and, where necessary, alpha
986premultiplication.
987
988    png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB);
989
990Choices for the alpha_mode are
991
992    PNG_ALPHA_PNG           0 /* according to the PNG standard */
993    PNG_ALPHA_STANDARD      1 /* according to Porter/Duff */
994    PNG_ALPHA_ASSOCIATED    1 /* as above; this is the normal practice */
995    PNG_ALPHA_PREMULTIPLIED 1 /* as above */
996    PNG_ALPHA_OPTIMIZED     2 /* 'PNG' for opaque pixels, else 'STANDARD' */
997    PNG_ALPHA_BROKEN        3 /* the alpha channel is gamma encoded */
998
999PNG_ALPHA_PNG is the default libpng handling of the alpha channel. It is not
1000pre-multiplied into the color components. In addition the call states
1001that the output is for a sRGB system and causes all PNG files without gAMA
1002chunks to be assumed to be encoded using sRGB.
1003
1004    png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC);
1005
1006In this case the output is assumed to be something like an sRGB conformant
1007display preceded by a power-law lookup table of power 1.45.  This is how
1008early Mac systems behaved.
1009
1010    png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_GAMMA_LINEAR);
1011
1012This is the classic Jim Blinn approach and will work in academic
1013environments where everything is done by the book.  It has the shortcoming
1014of assuming that input PNG data with no gamma information is linear - this
1015is unlikely to be correct unless the PNG files were generated locally.
1016Most of the time the output precision will be so low as to show
1017significant banding in dark areas of the image.
1018
1019    png_set_expand_16(pp);
1020    png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_DEFAULT_sRGB);
1021
1022This is a somewhat more realistic Jim Blinn inspired approach.  PNG files
1023are assumed to have the sRGB encoding if not marked with a gamma value and
1024the output is always 16 bits per component.  This permits accurate scaling
1025and processing of the data.  If you know that your input PNG files were
1026generated locally you might need to replace PNG_DEFAULT_sRGB with the
1027correct value for your system.
1028
1029    png_set_alpha_mode(pp, PNG_ALPHA_OPTIMIZED, PNG_DEFAULT_sRGB);
1030
1031If you just need to composite the PNG image onto an existing background
1032and if you control the code that does this you can use the optimization
1033setting.  In this case you just copy completely opaque pixels to the
1034output.  For pixels that are not completely transparent (you just skip
1035those) you do the composition math using png_composite or png_composite_16
1036below then encode the resultant 8-bit or 16-bit values to match the output
1037encoding.
1038
1039    Other cases
1040
1041If neither the PNG nor the standard linear encoding work for you because
1042of the software or hardware you use then you have a big problem.  The PNG
1043case will probably result in halos around the image.  The linear encoding
1044will probably result in a washed out, too bright, image (it's actually too
1045contrasty.)  Try the ALPHA_OPTIMIZED mode above - this will probably
1046substantially reduce the halos.  Alternatively try:
1047
1048    png_set_alpha_mode(pp, PNG_ALPHA_BROKEN, PNG_DEFAULT_sRGB);
1049
1050This option will also reduce the halos, but there will be slight dark
1051halos round the opaque parts of the image where the background is light.
1052In the OPTIMIZED mode the halos will be light halos where the background
1053is dark.  Take your pick - the halos are unavoidable unless you can get
1054your hardware/software fixed!  (The OPTIMIZED approach is slightly
1055faster.)
1056
1057When the default gamma of PNG files doesn't match the output gamma.
1058If you have PNG files with no gamma information png_set_alpha_mode allows
1059you to provide a default gamma, but it also sets the output gamma to the
1060matching value.  If you know your PNG files have a gamma that doesn't
1061match the output you can take advantage of the fact that
1062png_set_alpha_mode always sets the output gamma but only sets the PNG
1063default if it is not already set:
1064
1065    png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB);
1066    png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC);
1067
1068The first call sets both the default and the output gamma values, the
1069second call overrides the output gamma without changing the default.  This
1070is easier than achieving the same effect with png_set_gamma.  You must use
1071PNG_ALPHA_PNG for the first call - internal checking in png_set_alpha will
1072fire if more than one call to png_set_alpha_mode and png_set_background is
1073made in the same read operation, however multiple calls with PNG_ALPHA_PNG
1074are ignored.
1075
1076If you don't need, or can't handle, the alpha channel you can call
1077png_set_background() to remove it by compositing against a fixed color.  Don't
1078call png_set_strip_alpha() to do this - it will leave spurious pixel values in
1079transparent parts of this image.
1080
1081   png_set_background(png_ptr, &background_color,
1082       PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
1083
1084The background_color is an RGB or grayscale value according to the data format
1085libpng will produce for you.  Because you don't yet know the format of the PNG
1086file, if you call png_set_background at this point you must arrange for the
1087format produced by libpng to always have 8-bit or 16-bit components and then
1088store the color as an 8-bit or 16-bit color as appropriate.  The color contains
1089separate gray and RGB component values, so you can let libpng produce gray or
1090RGB output according to the input format, but low bit depth grayscale images
1091must always be converted to at least 8-bit format.  (Even though low bit depth
1092grayscale images can't have an alpha channel they can have a transparent
1093color!)
1094
1095You set the transforms you need later, either as flags to the high level
1096interface or libpng API calls for the low level interface.  For reference the
1097settings and API calls required are:
1098
10998-bit values:
1100   PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
1101   png_set_expand(png_ptr); png_set_scale_16(png_ptr);
1102
1103   If you must get exactly the same inaccurate results
1104   produced by default in versions prior to libpng-1.5.4,
1105   use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr)
1106   instead.
1107
110816-bit values:
1109   PNG_TRANSFORM_EXPAND_16
1110   png_set_expand_16(png_ptr);
1111
1112In either case palette image data will be expanded to RGB.  If you just want
1113color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
1114to the list.
1115
1116Calling png_set_background before the PNG file header is read will not work
1117prior to libpng-1.5.4.  Because the failure may result in unexpected warnings or
1118errors it is therefore much safer to call png_set_background after the head has
1119been read.  Unfortunately this means that prior to libpng-1.5.4 it cannot be
1120used with the high level interface.
1121
1122The high-level read interface
1123
1124At this point there are two ways to proceed; through the high-level
1125read interface, or through a sequence of low-level read operations.
1126You can use the high-level interface if (a) you are willing to read
1127the entire image into memory, and (b) the input transformations
1128you want to do are limited to the following set:
1129
1130    PNG_TRANSFORM_IDENTITY      No transformation
1131    PNG_TRANSFORM_SCALE_16      Strip 16-bit samples to
1132                                8-bit accurately
1133    PNG_TRANSFORM_STRIP_16      Chop 16-bit samples to
1134                                8-bit less accurately
1135    PNG_TRANSFORM_STRIP_ALPHA   Discard the alpha channel
1136    PNG_TRANSFORM_PACKING       Expand 1, 2 and 4-bit
1137                                samples to bytes
1138    PNG_TRANSFORM_PACKSWAP      Change order of packed
1139                                pixels to LSB first
1140    PNG_TRANSFORM_EXPAND        Perform set_expand()
1141    PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
1142    PNG_TRANSFORM_SHIFT         Normalize pixels to the
1143                                sBIT depth
1144    PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
1145                                to BGRA
1146    PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
1147                                to AG
1148    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
1149                                to transparency
1150    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
1151    PNG_TRANSFORM_GRAY_TO_RGB   Expand grayscale samples
1152                                to RGB (or GA to RGBA)
1153    PNG_TRANSFORM_EXPAND_16     Expand samples to 16 bits
1154
1155(This excludes setting a background color, doing gamma transformation,
1156quantizing, and setting filler.)  If this is the case, simply do this:
1157
1158    png_read_png(png_ptr, info_ptr, png_transforms, NULL)
1159
1160where png_transforms is an integer containing the bitwise OR of some
1161set of transformation flags.  This call is equivalent to png_read_info(),
1162followed the set of transformations indicated by the transform mask,
1163then png_read_image(), and finally png_read_end().
1164
1165(The final parameter of this call is not yet used.  Someday it might point
1166to transformation parameters required by some future input transform.)
1167
1168You must use png_transforms and not call any png_set_transform() functions
1169when you use png_read_png().
1170
1171After you have called png_read_png(), you can retrieve the image data
1172with
1173
1174   row_pointers = png_get_rows(png_ptr, info_ptr);
1175
1176where row_pointers is an array of pointers to the pixel data for each row:
1177
1178   png_bytep row_pointers[height];
1179
1180If you know your image size and pixel size ahead of time, you can allocate
1181row_pointers prior to calling png_read_png() with
1182
1183   if (height > PNG_UINT_32_MAX/(sizeof (png_byte)))
1184      png_error (png_ptr,
1185          "Image is too tall to process in memory");
1186
1187   if (width > PNG_UINT_32_MAX/pixel_size)
1188      png_error (png_ptr,
1189          "Image is too wide to process in memory");
1190
1191   row_pointers = png_malloc(png_ptr,
1192       height*(sizeof (png_bytep)));
1193
1194   for (int i=0; i<height, i++)
1195      row_pointers[i]=NULL;  /* security precaution */
1196
1197   for (int i=0; i<height, i++)
1198      row_pointers[i]=png_malloc(png_ptr,
1199          width*pixel_size);
1200
1201   png_set_rows(png_ptr, info_ptr, &row_pointers);
1202
1203Alternatively you could allocate your image in one big block and define
1204row_pointers[i] to point into the proper places in your block, but first
1205be sure that your platform is able to allocate such a large buffer:
1206
1207   /* Guard against integer overflow */
1208   if (height > PNG_SIZE_MAX/(width*pixel_size)) {
1209        png_error(png_ptr,"image_data buffer would be too large");
1210   }
1211
1212   png_bytep buffer=png_malloc(png_ptr,height*width*pixel_size);
1213
1214   for (int i=0; i<height, i++)
1215      row_pointers[i]=buffer+i*width*pixel_size;
1216
1217   png_set_rows(png_ptr, info_ptr, &row_pointers);
1218
1219If you use png_set_rows(), the application is responsible for freeing
1220row_pointers (and row_pointers[i], if they were separately allocated).
1221
1222If you don't allocate row_pointers ahead of time, png_read_png() will
1223do it, and it'll be free'ed by libpng when you call png_destroy_*().
1224
1225The low-level read interface
1226
1227If you are going the low-level route, you are now ready to read all
1228the file information up to the actual image data.  You do this with a
1229call to png_read_info().
1230
1231    png_read_info(png_ptr, info_ptr);
1232
1233This will process all chunks up to but not including the image data.
1234
1235This also copies some of the data from the PNG file into the decode structure
1236for use in later transformations.  Important information copied in is:
1237
12381) The PNG file gamma from the gAMA chunk.  This overwrites the default value
1239provided by an earlier call to png_set_gamma or png_set_alpha_mode.
1240
12412) Prior to libpng-1.5.4 the background color from a bKGd chunk.  This
1242damages the information provided by an earlier call to png_set_background
1243resulting in unexpected behavior.  Libpng-1.5.4 no longer does this.
1244
12453) The number of significant bits in each component value.  Libpng uses this to
1246optimize gamma handling by reducing the internal lookup table sizes.
1247
12484) The transparent color information from a tRNS chunk.  This can be modified by
1249a later call to png_set_tRNS.
1250
1251Querying the info structure
1252
1253Functions are used to get the information from the info_ptr once it
1254has been read.  Note that these fields may not be completely filled
1255in until png_read_end() has read the chunk data following the image.
1256
1257    png_get_IHDR(png_ptr, info_ptr, &width, &height,
1258       &bit_depth, &color_type, &interlace_type,
1259       &compression_type, &filter_method);
1260
1261    width          - holds the width of the image
1262                     in pixels (up to 2^31).
1263
1264    height         - holds the height of the image
1265                     in pixels (up to 2^31).
1266
1267    bit_depth      - holds the bit depth of one of the
1268                     image channels.  (valid values are
1269                     1, 2, 4, 8, 16 and depend also on
1270                     the color_type.  See also
1271                     significant bits (sBIT) below).
1272
1273    color_type     - describes which color/alpha channels
1274                         are present.
1275                     PNG_COLOR_TYPE_GRAY
1276                        (bit depths 1, 2, 4, 8, 16)
1277                     PNG_COLOR_TYPE_GRAY_ALPHA
1278                        (bit depths 8, 16)
1279                     PNG_COLOR_TYPE_PALETTE
1280                        (bit depths 1, 2, 4, 8)
1281                     PNG_COLOR_TYPE_RGB
1282                        (bit_depths 8, 16)
1283                     PNG_COLOR_TYPE_RGB_ALPHA
1284                        (bit_depths 8, 16)
1285
1286                     PNG_COLOR_MASK_PALETTE
1287                     PNG_COLOR_MASK_COLOR
1288                     PNG_COLOR_MASK_ALPHA
1289
1290    interlace_type - (PNG_INTERLACE_NONE or
1291                     PNG_INTERLACE_ADAM7)
1292
1293    compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1294                     for PNG 1.0)
1295
1296    filter_method  - (must be PNG_FILTER_TYPE_BASE
1297                     for PNG 1.0, and can also be
1298                     PNG_INTRAPIXEL_DIFFERENCING if
1299                     the PNG datastream is embedded in
1300                     a MNG-1.0 datastream)
1301
1302    Any of width, height, color_type, bit_depth,
1303    interlace_type, compression_type, or filter_method can
1304    be NULL if you are not interested in their values.
1305
1306    Note that png_get_IHDR() returns 32-bit data into
1307    the application's width and height variables.
1308    This is an unsafe situation if these are not png_uint_32
1309    variables.  In such situations, the
1310    png_get_image_width() and png_get_image_height()
1311    functions described below are safer.
1312
1313    width            = png_get_image_width(png_ptr,
1314                         info_ptr);
1315
1316    height           = png_get_image_height(png_ptr,
1317                         info_ptr);
1318
1319    bit_depth        = png_get_bit_depth(png_ptr,
1320                         info_ptr);
1321
1322    color_type       = png_get_color_type(png_ptr,
1323                         info_ptr);
1324
1325    interlace_type   = png_get_interlace_type(png_ptr,
1326                         info_ptr);
1327
1328    compression_type = png_get_compression_type(png_ptr,
1329                         info_ptr);
1330
1331    filter_method    = png_get_filter_type(png_ptr,
1332                         info_ptr);
1333
1334    channels = png_get_channels(png_ptr, info_ptr);
1335
1336    channels       - number of channels of info for the
1337                     color type (valid values are 1 (GRAY,
1338                     PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1339                     4 (RGB_ALPHA or RGB + filler byte))
1340
1341    rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1342
1343    rowbytes       - number of bytes needed to hold a row
1344                     This value, the bit_depth, color_type,
1345                     and the number of channels can change
1346                     if you use transforms such as
1347                     png_set_expand(). See
1348                     png_read_update_info(), below.
1349
1350    signature = png_get_signature(png_ptr, info_ptr);
1351
1352    signature      - holds the signature read from the
1353                     file (if any).  The data is kept in
1354                     the same offset it would be if the
1355                     whole signature were read (i.e. if an
1356                     application had already read in 4
1357                     bytes of signature before starting
1358                     libpng, the remaining 4 bytes would
1359                     be in signature[4] through signature[7]
1360                     (see png_set_sig_bytes())).
1361
1362These are also important, but their validity depends on whether the chunk
1363has been read.  The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1364png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1365data has been read, or zero if it is missing.  The parameters to the
1366png_get_<chunk> are set directly if they are simple data types, or a
1367pointer into the info_ptr is returned for any complex types.
1368
1369The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks
1370is simply returned to give the application information about how the
1371image was encoded.  Libpng itself only does transformations using the file
1372gamma when combining semitransparent pixels with the background color, and,
1373since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels
1374within the simplified API.  Libpng also uses the file gamma when converting
1375RGB to gray, beginning with libpng-1.0.5, if the application calls
1376png_set_rgb_to_gray()).
1377
1378    png_get_PLTE(png_ptr, info_ptr, &palette,
1379                     &num_palette);
1380
1381    palette        - the palette for the file
1382                     (array of png_color)
1383
1384    num_palette    - number of entries in the palette
1385
1386    png_get_gAMA(png_ptr, info_ptr, &file_gamma);
1387    png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
1388
1389    file_gamma     - the gamma at which the file is
1390                     written (PNG_INFO_gAMA)
1391
1392    int_file_gamma - 100,000 times the gamma at which the
1393                     file is written
1394
1395    png_get_cHRM(png_ptr, info_ptr,  &white_x, &white_y, &red_x,
1396                     &red_y, &green_x, &green_y, &blue_x, &blue_y)
1397    png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z,
1398                     &green_X, &green_Y, &green_Z, &blue_X, &blue_Y,
1399                     &blue_Z)
1400    png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x,
1401                     &int_white_y, &int_red_x, &int_red_y,
1402                     &int_green_x, &int_green_y, &int_blue_x,
1403                     &int_blue_y)
1404    png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
1405                     &int_red_Z, &int_green_X, &int_green_Y,
1406                     &int_green_Z, &int_blue_X, &int_blue_Y,
1407                     &int_blue_Z)
1408
1409    {white,red,green,blue}_{x,y}
1410                     A color space encoding specified using the
1411                     chromaticities of the end points and the
1412                     white point. (PNG_INFO_cHRM)
1413
1414    {red,green,blue}_{X,Y,Z}
1415                     A color space encoding specified using the
1416                     encoding end points - the CIE tristimulus
1417                     specification of the intended color of the red,
1418                     green and blue channels in the PNG RGB data.
1419                     The white point is simply the sum of the three
1420                     end points. (PNG_INFO_cHRM)
1421
1422    png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1423
1424    srgb_intent -    the rendering intent (PNG_INFO_sRGB)
1425                     The presence of the sRGB chunk
1426                     means that the pixel data is in the
1427                     sRGB color space.  This chunk also
1428                     implies specific values of gAMA and
1429                     cHRM.
1430
1431    png_get_iCCP(png_ptr, info_ptr, &name,
1432       &compression_type, &profile, &proflen);
1433
1434    name             - The profile name.
1435
1436    compression_type - The compression type; always
1437                       PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1438                       You may give NULL to this argument to
1439                       ignore it.
1440
1441    profile          - International Color Consortium color
1442                       profile data. May contain NULs.
1443
1444    proflen          - length of profile data in bytes.
1445
1446    png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1447
1448    sig_bit        - the number of significant bits for
1449                     (PNG_INFO_sBIT) each of the gray,
1450                     red, green, and blue channels,
1451                     whichever are appropriate for the
1452                     given color type (png_color_16)
1453
1454    png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
1455                     &num_trans, &trans_color);
1456
1457    trans_alpha    - array of alpha (transparency)
1458                     entries for palette (PNG_INFO_tRNS)
1459
1460    num_trans      - number of transparent entries
1461                     (PNG_INFO_tRNS)
1462
1463    trans_color    - graylevel or color sample values of
1464                     the single transparent color for
1465                     non-paletted images (PNG_INFO_tRNS)
1466
1467    png_get_eXIf_1(png_ptr, info_ptr, &num_exif, &exif);
1468                     (PNG_INFO_eXIf)
1469
1470    exif           - Exif profile (array of png_byte)
1471
1472    png_get_hIST(png_ptr, info_ptr, &hist);
1473                     (PNG_INFO_hIST)
1474
1475    hist           - histogram of palette (array of
1476                     png_uint_16)
1477
1478    png_get_tIME(png_ptr, info_ptr, &mod_time);
1479
1480    mod_time       - time image was last modified
1481                    (PNG_VALID_tIME)
1482
1483    png_get_bKGD(png_ptr, info_ptr, &background);
1484
1485    background     - background color (of type
1486                     png_color_16p) (PNG_VALID_bKGD)
1487                     valid 16-bit red, green and blue
1488                     values, regardless of color_type
1489
1490    num_comments   = png_get_text(png_ptr, info_ptr,
1491                     &text_ptr, &num_text);
1492
1493    num_comments   - number of comments
1494
1495    text_ptr       - array of png_text holding image
1496                     comments
1497
1498    text_ptr[i].compression - type of compression used
1499                 on "text" PNG_TEXT_COMPRESSION_NONE
1500                           PNG_TEXT_COMPRESSION_zTXt
1501                           PNG_ITXT_COMPRESSION_NONE
1502                           PNG_ITXT_COMPRESSION_zTXt
1503
1504    text_ptr[i].key   - keyword for comment.  Must contain
1505                         1-79 characters.
1506
1507    text_ptr[i].text  - text comments for current
1508                         keyword.  Can be empty.
1509
1510    text_ptr[i].text_length - length of text string,
1511                 after decompression, 0 for iTXt
1512
1513    text_ptr[i].itxt_length - length of itxt string,
1514                 after decompression, 0 for tEXt/zTXt
1515
1516    text_ptr[i].lang  - language of comment (empty
1517                         string for unknown).
1518
1519    text_ptr[i].lang_key  - keyword in UTF-8
1520                         (empty string for unknown).
1521
1522    Note that the itxt_length, lang, and lang_key
1523    members of the text_ptr structure only exist when the
1524    library is built with iTXt chunk support.  Prior to
1525    libpng-1.4.0 the library was built by default without
1526    iTXt support. Also note that when iTXt is supported,
1527    they contain NULL pointers when the "compression"
1528    field contains PNG_TEXT_COMPRESSION_NONE or
1529    PNG_TEXT_COMPRESSION_zTXt.
1530
1531    num_text       - number of comments (same as
1532                     num_comments; you can put NULL here
1533                     to avoid the duplication)
1534
1535    Note while png_set_text() will accept text, language,
1536    and translated keywords that can be NULL pointers, the
1537    structure returned by png_get_text will always contain
1538    regular zero-terminated C strings.  They might be
1539    empty strings but they will never be NULL pointers.
1540
1541    num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1542       &palette_ptr);
1543
1544    num_spalettes  - number of sPLT chunks read.
1545
1546    palette_ptr    - array of palette structures holding
1547                     contents of one or more sPLT chunks
1548                     read.
1549
1550    png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1551       &unit_type);
1552
1553    offset_x       - positive offset from the left edge
1554                     of the screen (can be negative)
1555
1556    offset_y       - positive offset from the top edge
1557                     of the screen (can be negative)
1558
1559    unit_type      - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1560
1561    png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1562       &unit_type);
1563
1564    res_x          - pixels/unit physical resolution in
1565                     x direction
1566
1567    res_y          - pixels/unit physical resolution in
1568                     x direction
1569
1570    unit_type      - PNG_RESOLUTION_UNKNOWN,
1571                     PNG_RESOLUTION_METER
1572
1573    png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1574       &height)
1575
1576    unit        - physical scale units (an integer)
1577
1578    width       - width of a pixel in physical scale units
1579
1580    height      - height of a pixel in physical scale units
1581                 (width and height are doubles)
1582
1583    png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1584       &height)
1585
1586    unit        - physical scale units (an integer)
1587
1588    width       - width of a pixel in physical scale units
1589                  (expressed as a string)
1590
1591    height      - height of a pixel in physical scale units
1592                 (width and height are strings like "2.54")
1593
1594    num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1595       info_ptr, &unknowns)
1596
1597    unknowns          - array of png_unknown_chunk
1598                        structures holding unknown chunks
1599
1600    unknowns[i].name  - name of unknown chunk
1601
1602    unknowns[i].data  - data of unknown chunk
1603
1604    unknowns[i].size  - size of unknown chunk's data
1605
1606    unknowns[i].location - position of chunk in file
1607
1608    The value of "i" corresponds to the order in which the
1609    chunks were read from the PNG file or inserted with the
1610    png_set_unknown_chunks() function.
1611
1612    The value of "location" is a bitwise "or" of
1613
1614         PNG_HAVE_IHDR  (0x01)
1615         PNG_HAVE_PLTE  (0x02)
1616         PNG_AFTER_IDAT (0x08)
1617
1618The data from the pHYs chunk can be retrieved in several convenient
1619forms:
1620
1621    res_x = png_get_x_pixels_per_meter(png_ptr,
1622       info_ptr)
1623
1624    res_y = png_get_y_pixels_per_meter(png_ptr,
1625       info_ptr)
1626
1627    res_x_and_y = png_get_pixels_per_meter(png_ptr,
1628       info_ptr)
1629
1630    res_x = png_get_x_pixels_per_inch(png_ptr,
1631       info_ptr)
1632
1633    res_y = png_get_y_pixels_per_inch(png_ptr,
1634       info_ptr)
1635
1636    res_x_and_y = png_get_pixels_per_inch(png_ptr,
1637       info_ptr)
1638
1639    aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1640       info_ptr)
1641
1642    Each of these returns 0 [signifying "unknown"] if
1643       the data is not present or if res_x is 0;
1644       res_x_and_y is 0 if res_x != res_y
1645
1646    Note that because of the way the resolutions are
1647       stored internally, the inch conversions won't
1648       come out to exactly even number.  For example,
1649       72 dpi is stored as 0.28346 pixels/meter, and
1650       when this is retrieved it is 71.9988 dpi, so
1651       be sure to round the returned value appropriately
1652       if you want to display a reasonable-looking result.
1653
1654The data from the oFFs chunk can be retrieved in several convenient
1655forms:
1656
1657    x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1658
1659    y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1660
1661    x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1662
1663    y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1664
1665    Each of these returns 0 [signifying "unknown" if both
1666       x and y are 0] if the data is not present or if the
1667       chunk is present but the unit is the pixel.  The
1668       remark about inexact inch conversions applies here
1669       as well, because a value in inches can't always be
1670       converted to microns and back without some loss
1671       of precision.
1672
1673For more information, see the
1674PNG specification for chunk contents.  Be careful with trusting
1675rowbytes, as some of the transformations could increase the space
1676needed to hold a row (expand, filler, gray_to_rgb, etc.).
1677See png_read_update_info(), below.
1678
1679A quick word about text_ptr and num_text.  PNG stores comments in
1680keyword/text pairs, one pair per chunk, with no limit on the number
1681of text chunks, and a 2^31 byte limit on their size.  While there are
1682suggested keywords, there is no requirement to restrict the use to these
1683strings.  It is strongly suggested that keywords and text be sensible
1684to humans (that's the point), so don't use abbreviations.  Non-printing
1685symbols are not allowed.  See the PNG specification for more details.
1686There is also no requirement to have text after the keyword.
1687
1688Keywords should be limited to 79 Latin-1 characters without leading or
1689trailing spaces, but non-consecutive spaces are allowed within the
1690keyword.  It is possible to have the same keyword any number of times.
1691The text_ptr is an array of png_text structures, each holding a
1692pointer to a language string, a pointer to a keyword and a pointer to
1693a text string.  The text string, language code, and translated
1694keyword may be empty or NULL pointers.  The keyword/text
1695pairs are put into the array in the order that they are received.
1696However, some or all of the text chunks may be after the image, so, to
1697make sure you have read all the text chunks, don't mess with these
1698until after you read the stuff after the image.  This will be
1699mentioned again below in the discussion that goes with png_read_end().
1700
1701Input transformations
1702
1703After you've read the header information, you can set up the library
1704to handle any special transformations of the image data.  The various
1705ways to transform the data will be described in the order that they
1706should occur.  This is important, as some of these change the color
1707type and/or bit depth of the data, and some others only work on
1708certain color types and bit depths.
1709
1710Transformations you request are ignored if they don't have any meaning for a
1711particular input data format.  However some transformations can have an effect
1712as a result of a previous transformation.  If you specify a contradictory set of
1713transformations, for example both adding and removing the alpha channel, you
1714cannot predict the final result.
1715
1716The color used for the transparency values should be supplied in the same
1717format/depth as the current image data.  It is stored in the same format/depth
1718as the image data in a tRNS chunk, so this is what libpng expects for this data.
1719
1720The color used for the background value depends on the need_expand argument as
1721described below.
1722
1723Data will be decoded into the supplied row buffers packed into bytes
1724unless the library has been told to transform it into another format.
1725For example, 4 bit/pixel paletted or grayscale data will be returned
17262 pixels/byte with the leftmost pixel in the high-order bits of the byte,
1727unless png_set_packing() is called.  8-bit RGB data will be stored
1728in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
1729is called to insert filler bytes, either before or after each RGB triplet.
1730
173116-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
1732byte of the color value first, unless png_set_scale_16() is called to
1733transform it to regular RGB RGB triplets, or png_set_filler() or
1734png_set_add alpha() is called to insert two filler bytes, either before
1735or after each RRGGBB triplet.  Similarly, 8-bit or 16-bit grayscale data can
1736be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(),
1737or png_set_scale_16().
1738
1739The following code transforms grayscale images of less than 8 to 8 bits,
1740changes paletted images to RGB, and adds a full alpha channel if there is
1741transparency information in a tRNS chunk.  This is most useful on
1742grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1743viewing application that wishes to treat all images in the same way.
1744
1745    if (color_type == PNG_COLOR_TYPE_PALETTE)
1746        png_set_palette_to_rgb(png_ptr);
1747
1748    if (png_get_valid(png_ptr, info_ptr,
1749        PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1750
1751    if (color_type == PNG_COLOR_TYPE_GRAY &&
1752        bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
1753
1754The first two functions are actually aliases for png_set_expand(), added
1755in libpng version 1.0.4, with the function names expanded to improve code
1756readability.  In some future version they may actually do different
1757things.
1758
1759As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
1760added.  It expands the sample depth without changing tRNS to alpha.
1761
1762As of libpng version 1.5.2, png_set_expand_16() was added.  It behaves as
1763png_set_expand(); however, the resultant channels have 16 bits rather than 8.
1764Use this when the output color or gray channels are made linear to avoid fairly
1765severe accuracy loss.
1766
1767   if (bit_depth < 16)
1768      png_set_expand_16(png_ptr);
1769
1770PNG can have files with 16 bits per channel.  If you only can handle
17718 bits per channel, this will strip the pixels down to 8-bit.
1772
1773    if (bit_depth == 16)
1774#if PNG_LIBPNG_VER >= 10504
1775       png_set_scale_16(png_ptr);
1776#else
1777       png_set_strip_16(png_ptr);
1778#endif
1779
1780(The more accurate "png_set_scale_16()" API became available in libpng version
17811.5.4).
1782
1783If you need to process the alpha channel on the image separately from the image
1784data (for example if you convert it to a bitmap mask) it is possible to have
1785libpng strip the channel leaving just RGB or gray data:
1786
1787    if (color_type & PNG_COLOR_MASK_ALPHA)
1788       png_set_strip_alpha(png_ptr);
1789
1790If you strip the alpha channel you need to find some other way of dealing with
1791the information.  If, instead, you want to convert the image to an opaque
1792version with no alpha channel use png_set_background; see below.
1793
1794As of libpng version 1.5.2, almost all useful expansions are supported, the
1795major ommissions are conversion of grayscale to indexed images (which can be
1796done trivially in the application) and conversion of indexed to grayscale (which
1797can be done by a trivial manipulation of the palette.)
1798
1799In the following table, the 01 means grayscale with depth<8, 31 means
1800indexed with depth<8, other numerals represent the color type, "T" means
1801the tRNS chunk is present, A means an alpha channel is present, and O
1802means tRNS or alpha is present but all pixels in the image are opaque.
1803
1804  FROM  01  31   0  0T  0O   2  2T  2O   3  3T  3O  4A  4O  6A  6O
1805   TO
1806   01    -  [G]  -   -   -   -   -   -   -   -   -   -   -   -   -
1807   31   [Q]  Q  [Q] [Q] [Q]  Q   Q   Q   Q   Q   Q  [Q] [Q]  Q   Q
1808    0    1   G   +   .   .   G   G   G   G   G   G   B   B  GB  GB
1809   0T    lt  Gt  t   +   .   Gt  G   G   Gt  G   G   Bt  Bt GBt GBt
1810   0O    lt  Gt  t   .   +   Gt  Gt  G   Gt  Gt  G   Bt  Bt GBt GBt
1811    2    C   P   C   C   C   +   .   .   C   -   -  CB  CB   B   B
1812   2T    Ct  -   Ct  C   C   t   +   t   -   -   -  CBt CBt  Bt  Bt
1813   2O    Ct  -   Ct  C   C   t   t   +   -   -   -  CBt CBt  Bt  Bt
1814    3   [Q]  p  [Q] [Q] [Q]  Q   Q   Q   +   .   .  [Q] [Q]  Q   Q
1815   3T   [Qt] p  [Qt][Q] [Q]  Qt  Qt  Qt  t   +   t  [Qt][Qt] Qt  Qt
1816   3O   [Qt] p  [Qt][Q] [Q]  Qt  Qt  Qt  t   t   +  [Qt][Qt] Qt  Qt
1817   4A    lA  G   A   T   T   GA  GT  GT  GA  GT  GT  +   BA  G  GBA
1818   4O    lA GBA  A   T   T   GA  GT  GT  GA  GT  GT  BA  +  GBA  G
1819   6A    CA  PA  CA  C   C   A   T  tT   PA  P   P   C  CBA  +   BA
1820   6O    CA PBA  CA  C   C   A  tT   T   PA  P   P  CBA  C   BA  +
1821
1822Within the matrix,
1823     "+" identifies entries where 'from' and 'to' are the same.
1824     "-" means the transformation is not supported.
1825     "." means nothing is necessary (a tRNS chunk can just be ignored).
1826     "t" means the transformation is obtained by png_set_tRNS.
1827     "A" means the transformation is obtained by png_set_add_alpha().
1828     "X" means the transformation is obtained by png_set_expand().
1829     "1" means the transformation is obtained by
1830         png_set_expand_gray_1_2_4_to_8() (and by png_set_expand()
1831         if there is no transparency in the original or the final
1832         format).
1833     "C" means the transformation is obtained by png_set_gray_to_rgb().
1834     "G" means the transformation is obtained by png_set_rgb_to_gray().
1835     "P" means the transformation is obtained by
1836         png_set_expand_palette_to_rgb().
1837     "p" means the transformation is obtained by png_set_packing().
1838     "Q" means the transformation is obtained by png_set_quantize().
1839     "T" means the transformation is obtained by
1840         png_set_tRNS_to_alpha().
1841     "B" means the transformation is obtained by
1842         png_set_background(), or png_strip_alpha().
1843
1844When an entry has multiple transforms listed all are required to cause the
1845right overall transformation.  When two transforms are separated by a comma
1846either will do the job.  When transforms are enclosed in [] the transform should
1847do the job but this is currently unimplemented - a different format will result
1848if the suggested transformations are used.
1849
1850In PNG files, the alpha channel in an image
1851is the level of opacity.  If you need the alpha channel in an image to
1852be the level of transparency instead of opacity, you can invert the
1853alpha channel (or the tRNS chunk data) after it's read, so that 0 is
1854fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
1855images) is fully transparent, with
1856
1857    png_set_invert_alpha(png_ptr);
1858
1859PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1860they can, resulting in, for example, 8 pixels per byte for 1 bit
1861files.  This code expands to 1 pixel per byte without changing the
1862values of the pixels:
1863
1864    if (bit_depth < 8)
1865       png_set_packing(png_ptr);
1866
1867PNG files have possible bit depths of 1, 2, 4, 8, and 16.  All pixels
1868stored in a PNG image have been "scaled" or "shifted" up to the next
1869higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
1870to 8 bits/sample in the range [0, 255]).  However, it is also possible
1871to convert the PNG pixel data back to the original bit depth of the
1872image.  This call reduces the pixels back down to the original bit depth:
1873
1874    png_color_8p sig_bit;
1875
1876    if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1877       png_set_shift(png_ptr, sig_bit);
1878
1879PNG files store 3-color pixels in red, green, blue order.  This code
1880changes the storage of the pixels to blue, green, red:
1881
1882    if (color_type == PNG_COLOR_TYPE_RGB ||
1883        color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1884       png_set_bgr(png_ptr);
1885
1886PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
1887into 4 or 8 bytes for windowing systems that need them in this format:
1888
1889    if (color_type == PNG_COLOR_TYPE_RGB)
1890       png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
1891
1892where "filler" is the 8-bit or 16-bit number to fill with, and the location
1893is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1894you want the filler before the RGB or after. When filling an 8-bit pixel,
1895the least significant 8 bits of the number are used, if a 16-bit number is
1896supplied.  This transformation does not affect images that already have full
1897alpha channels.  To add an opaque alpha channel, use filler=0xffff and
1898PNG_FILLER_AFTER which will generate RGBA pixels.
1899
1900Note that png_set_filler() does not change the color type.  If you want
1901to do that, you can add a true alpha channel with
1902
1903    if (color_type == PNG_COLOR_TYPE_RGB ||
1904       color_type == PNG_COLOR_TYPE_GRAY)
1905       png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1906
1907where "filler" contains the alpha value to assign to each pixel.
1908The png_set_add_alpha() function was added in libpng-1.2.7.
1909
1910If you are reading an image with an alpha channel, and you need the
1911data as ARGB instead of the normal PNG format RGBA:
1912
1913    if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1914       png_set_swap_alpha(png_ptr);
1915
1916For some uses, you may want a grayscale image to be represented as
1917RGB.  This code will do that conversion:
1918
1919    if (color_type == PNG_COLOR_TYPE_GRAY ||
1920        color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1921       png_set_gray_to_rgb(png_ptr);
1922
1923Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1924with alpha.
1925
1926    if (color_type == PNG_COLOR_TYPE_RGB ||
1927        color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1928       png_set_rgb_to_gray(png_ptr, error_action,
1929          double red_weight, double green_weight);
1930
1931    error_action = 1: silently do the conversion
1932
1933    error_action = 2: issue a warning if the original
1934                      image has any pixel where
1935                      red != green or red != blue
1936
1937    error_action = 3: issue an error and abort the
1938                      conversion if the original
1939                      image has any pixel where
1940                      red != green or red != blue
1941
1942    red_weight:       weight of red component
1943
1944    green_weight:     weight of green component
1945                      If either weight is negative, default
1946                      weights are used.
1947
1948In the corresponding fixed point API the red_weight and green_weight values are
1949simply scaled by 100,000:
1950
1951    png_set_rgb_to_gray(png_ptr, error_action,
1952       png_fixed_point red_weight,
1953       png_fixed_point green_weight);
1954
1955If you have set error_action = 1 or 2, you can
1956later check whether the image really was gray, after processing
1957the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1958It will return a png_byte that is zero if the image was gray or
19591 if there were any non-gray pixels.  Background and sBIT data
1960will be silently converted to grayscale, using the green channel
1961data for sBIT, regardless of the error_action setting.
1962
1963The default values come from the PNG file cHRM chunk if present; otherwise, the
1964defaults correspond to the ITU-R recommendation 709, and also the sRGB color
1965space, as recommended in the Charles Poynton's Colour FAQ,
1966Copyright (c) 2006-11-28 Charles Poynton, in section 9:
1967
1968<http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
1969
1970    Y = 0.2126 * R + 0.7152 * G + 0.0722 * B
1971
1972Previous versions of this document, 1998 through 2002, recommended a slightly
1973different formula:
1974
1975    Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1976
1977Libpng uses an integer approximation:
1978
1979    Y = (6968 * R + 23434 * G + 2366 * B)/32768
1980
1981The calculation is done in a linear colorspace, if the image gamma
1982can be determined.
1983
1984The png_set_background() function has been described already; it tells libpng to
1985composite images with alpha or simple transparency against the supplied
1986background color.  For compatibility with versions of libpng earlier than
1987libpng-1.5.4 it is recommended that you call the function after reading the file
1988header, even if you don't want to use the color in a bKGD chunk, if one exists.
1989
1990If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1991you may use this color, or supply another color more suitable for
1992the current display (e.g., the background color from a web page).  You
1993need to tell libpng how the color is represented, both the format of the
1994component values in the color (the number of bits) and the gamma encoding of the
1995color.  The function takes two arguments, background_gamma_mode and need_expand
1996to convey this information; however, only two combinations are likely to be
1997useful:
1998
1999    png_color_16 my_background;
2000    png_color_16p image_background;
2001
2002    if (png_get_bKGD(png_ptr, info_ptr, &image_background))
2003       png_set_background(png_ptr, image_background,
2004           PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
2005    else
2006       png_set_background(png_ptr, &my_background,
2007           PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
2008
2009The second call was described above - my_background is in the format of the
2010final, display, output produced by libpng.  Because you now know the format of
2011the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
2012output and to retain palette images (the palette colors will be modified
2013appropriately and the tRNS chunk removed.)  However, if you are doing this,
2014take great care not to ask for transformations without checking first that
2015they apply!
2016
2017In the first call the background color has the original bit depth and color type
2018of the PNG file.  So, for palette images the color is supplied as a palette
2019index and for low bit greyscale images the color is a reduced bit value in
2020image_background->gray.
2021
2022If you didn't call png_set_gamma() before reading the file header, for example
2023if you need your code to remain compatible with older versions of libpng prior
2024to libpng-1.5.4, this is the place to call it.
2025
2026Do not call it if you called png_set_alpha_mode(); doing so will damage the
2027settings put in place by png_set_alpha_mode().  (If png_set_alpha_mode() is
2028supported then you can certainly do png_set_gamma() before reading the PNG
2029header.)
2030
2031This API unconditionally sets the screen and file gamma values, so it will
2032override the value in the PNG file unless it is called before the PNG file
2033reading starts.  For this reason you must always call it with the PNG file
2034value when you call it in this position:
2035
2036   if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
2037      png_set_gamma(png_ptr, screen_gamma, file_gamma);
2038
2039   else
2040      png_set_gamma(png_ptr, screen_gamma, 0.45455);
2041
2042If you need to reduce an RGB file to a paletted file, or if a paletted
2043file has more entries than will fit on your screen, png_set_quantize()
2044will do that.  Note that this is a simple match quantization that merely
2045finds the closest color available.  This should work fairly well with
2046optimized palettes, but fairly badly with linear color cubes.  If you
2047pass a palette that is larger than maximum_colors, the file will
2048reduce the number of colors in the palette so it will fit into
2049maximum_colors.  If there is a histogram, libpng will use it to make
2050more intelligent choices when reducing the palette.  If there is no
2051histogram, it may not do as good a job.
2052
2053   if (color_type & PNG_COLOR_MASK_COLOR)
2054   {
2055      if (png_get_valid(png_ptr, info_ptr,
2056          PNG_INFO_PLTE))
2057      {
2058         png_uint_16p histogram = NULL;
2059
2060         png_get_hIST(png_ptr, info_ptr,
2061             &histogram);
2062         png_set_quantize(png_ptr, palette, num_palette,
2063            max_screen_colors, histogram, 1);
2064      }
2065
2066      else
2067      {
2068         png_color std_color_cube[MAX_SCREEN_COLORS] =
2069            { ... colors ... };
2070
2071         png_set_quantize(png_ptr, std_color_cube,
2072            MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
2073            NULL,0);
2074      }
2075   }
2076
2077PNG files describe monochrome as black being zero and white being one.
2078The following code will reverse this (make black be one and white be
2079zero):
2080
2081   if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
2082      png_set_invert_mono(png_ptr);
2083
2084This function can also be used to invert grayscale and gray-alpha images:
2085
2086   if (color_type == PNG_COLOR_TYPE_GRAY ||
2087       color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
2088      png_set_invert_mono(png_ptr);
2089
2090PNG files store 16-bit pixels in network byte order (big-endian,
2091ie. most significant bits first).  This code changes the storage to the
2092other way (little-endian, i.e. least significant bits first, the
2093way PCs store them):
2094
2095    if (bit_depth == 16)
2096       png_set_swap(png_ptr);
2097
2098If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
2099need to change the order the pixels are packed into bytes, you can use:
2100
2101    if (bit_depth < 8)
2102       png_set_packswap(png_ptr);
2103
2104Finally, you can write your own transformation function if none of
2105the existing ones meets your needs.  This is done by setting a callback
2106with
2107
2108    png_set_read_user_transform_fn(png_ptr,
2109        read_transform_fn);
2110
2111You must supply the function
2112
2113    void read_transform_fn(png_structp png_ptr, png_row_infop
2114        row_info, png_bytep data)
2115
2116See pngtest.c for a working example.  Your function will be called
2117after all of the other transformations have been processed.  Take care with
2118interlaced images if you do the interlace yourself - the width of the row is the
2119width in 'row_info', not the overall image width.
2120
2121If supported, libpng provides two information routines that you can use to find
2122where you are in processing the image:
2123
2124   png_get_current_pass_number(png_structp png_ptr);
2125   png_get_current_row_number(png_structp png_ptr);
2126
2127Don't try using these outside a transform callback - firstly they are only
2128supported if user transforms are supported, secondly they may well return
2129unexpected results unless the row is actually being processed at the moment they
2130are called.
2131
2132With interlaced
2133images the value returned is the row in the input sub-image image.  Use
2134PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
2135find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
2136
2137The discussion of interlace handling above contains more information on how to
2138use these values.
2139
2140You can also set up a pointer to a user structure for use by your
2141callback function, and you can inform libpng that your transform
2142function will change the number of channels or bit depth with the
2143function
2144
2145    png_set_user_transform_info(png_ptr, user_ptr,
2146        user_depth, user_channels);
2147
2148The user's application, not libpng, is responsible for allocating and
2149freeing any memory required for the user structure.
2150
2151You can retrieve the pointer via the function
2152png_get_user_transform_ptr().  For example:
2153
2154    voidp read_user_transform_ptr =
2155        png_get_user_transform_ptr(png_ptr);
2156
2157The last thing to handle is interlacing; this is covered in detail below,
2158but you must call the function here if you want libpng to handle expansion
2159of the interlaced image.
2160
2161    number_of_passes = png_set_interlace_handling(png_ptr);
2162
2163After setting the transformations, libpng can update your png_info
2164structure to reflect any transformations you've requested with this
2165call.
2166
2167    png_read_update_info(png_ptr, info_ptr);
2168
2169This is most useful to update the info structure's rowbytes
2170field so you can use it to allocate your image memory.  This function
2171will also update your palette with the correct screen_gamma and
2172background if these have been given with the calls above.  You may
2173only call png_read_update_info() once with a particular info_ptr.
2174
2175After you call png_read_update_info(), you can allocate any
2176memory you need to hold the image.  The row data is simply
2177raw byte data for all forms of images.  As the actual allocation
2178varies among applications, no example will be given.  If you
2179are allocating one large chunk, you will need to build an
2180array of pointers to each row, as it will be needed for some
2181of the functions below.
2182
2183Be sure that your platform can allocate the buffer that you'll need.
2184libpng internally checks for oversize width, but you'll need to
2185do your own check for number_of_rows*width*pixel_size if you are using
2186a multiple-row buffer:
2187
2188   /* Guard against integer overflow */
2189   if (number_of_rows > PNG_SIZE_MAX/(width*pixel_size)) {
2190        png_error(png_ptr,"image_data buffer would be too large");
2191   }
2192
2193Remember: Before you call png_read_update_info(), the png_get_*()
2194functions return the values corresponding to the original PNG image.
2195After you call png_read_update_info the values refer to the image
2196that libpng will output.  Consequently you must call all the png_set_
2197functions before you call png_read_update_info().  This is particularly
2198important for png_set_interlace_handling() - if you are going to call
2199png_read_update_info() you must call png_set_interlace_handling() before
2200it unless you want to receive interlaced output.
2201
2202Reading image data
2203
2204After you've allocated memory, you can read the image data.
2205The simplest way to do this is in one function call.  If you are
2206allocating enough memory to hold the whole image, you can just
2207call png_read_image() and libpng will read in all the image data
2208and put it in the memory area supplied.  You will need to pass in
2209an array of pointers to each row.
2210
2211This function automatically handles interlacing, so you don't
2212need to call png_set_interlace_handling() (unless you call
2213png_read_update_info()) or call this function multiple times, or any
2214of that other stuff necessary with png_read_rows().
2215
2216   png_read_image(png_ptr, row_pointers);
2217
2218where row_pointers is:
2219
2220   png_bytep row_pointers[height];
2221
2222You can point to void or char or whatever you use for pixels.
2223
2224If you don't want to read in the whole image at once, you can
2225use png_read_rows() instead.  If there is no interlacing (check
2226interlace_type == PNG_INTERLACE_NONE), this is simple:
2227
2228    png_read_rows(png_ptr, row_pointers, NULL,
2229        number_of_rows);
2230
2231where row_pointers is the same as in the png_read_image() call.
2232
2233If you are doing this just one row at a time, you can do this with
2234a single row_pointer instead of an array of row_pointers:
2235
2236    png_bytep row_pointer = row;
2237    png_read_row(png_ptr, row_pointer, NULL);
2238
2239If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
2240get somewhat harder.  The only current (PNG Specification version 1.2)
2241interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
2242a somewhat complicated 2D interlace scheme, known as Adam7, that
2243breaks down an image into seven smaller images of varying size, based
2244on an 8x8 grid.  This number is defined (from libpng 1.5) as
2245PNG_INTERLACE_ADAM7_PASSES in png.h
2246
2247libpng can fill out those images or it can give them to you "as is".
2248It is almost always better to have libpng handle the interlacing for you.
2249If you want the images filled out, there are two ways to do that.  The one
2250mentioned in the PNG specification is to expand each pixel to cover
2251those pixels that have not been read yet (the "rectangle" method).
2252This results in a blocky image for the first pass, which gradually
2253smooths out as more pixels are read.  The other method is the "sparkle"
2254method, where pixels are drawn only in their final locations, with the
2255rest of the image remaining whatever colors they were initialized to
2256before the start of the read.  The first method usually looks better,
2257but tends to be slower, as there are more pixels to put in the rows.
2258
2259If, as is likely, you want libpng to expand the images, call this before
2260calling png_start_read_image() or png_read_update_info():
2261
2262    if (interlace_type == PNG_INTERLACE_ADAM7)
2263       number_of_passes
2264           = png_set_interlace_handling(png_ptr);
2265
2266This will return the number of passes needed.  Currently, this is seven,
2267but may change if another interlace type is added.  This function can be
2268called even if the file is not interlaced, where it will return one pass.
2269You then need to read the whole image 'number_of_passes' times.  Each time
2270will distribute the pixels from the current pass to the correct place in
2271the output image, so you need to supply the same rows to png_read_rows in
2272each pass.
2273
2274If you are not going to display the image after each pass, but are
2275going to wait until the entire image is read in, use the sparkle
2276effect.  This effect is faster and the end result of either method
2277is exactly the same.  If you are planning on displaying the image
2278after each pass, the "rectangle" effect is generally considered the
2279better looking one.
2280
2281If you only want the "sparkle" effect, just call png_read_row() or
2282png_read_rows() as
2283normal, with the third parameter NULL.  Make sure you make pass over
2284the image number_of_passes times, and you don't change the data in the
2285rows between calls.  You can change the locations of the data, just
2286not the data.  Each pass only writes the pixels appropriate for that
2287pass, and assumes the data from previous passes is still valid.
2288
2289    png_read_rows(png_ptr, row_pointers, NULL,
2290        number_of_rows);
2291    or
2292    png_read_row(png_ptr, row_pointers, NULL);
2293
2294If you only want the first effect (the rectangles), do the same as
2295before except pass the row buffer in the third parameter, and leave
2296the second parameter NULL.
2297
2298    png_read_rows(png_ptr, NULL, row_pointers,
2299        number_of_rows);
2300    or
2301    png_read_row(png_ptr, NULL, row_pointers);
2302
2303If you don't want libpng to handle the interlacing details, just call
2304png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
2305Each of the images is a valid image by itself; however, you will almost
2306certainly need to distribute the pixels from each sub-image to the
2307correct place.  This is where everything gets very tricky.
2308
2309If you want to retrieve the separate images you must pass the correct
2310number of rows to each successive call of png_read_rows().  The calculation
2311gets pretty complicated for small images, where some sub-images may
2312not even exist because either their width or height ends up zero.
2313libpng provides two macros to help you in 1.5 and later versions:
2314
2315   png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
2316   png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
2317
2318Respectively these tell you the width and height of the sub-image
2319corresponding to the numbered pass.  'pass' is in in the range 0 to 6 -
2320this can be confusing because the specification refers to the same passes
2321as 1 to 7!  Be careful, you must check both the width and height before
2322calling png_read_rows() and not call it for that pass if either is zero.
2323
2324You can, of course, read each sub-image row by row.  If you want to
2325produce optimal code to make a pixel-by-pixel transformation of an
2326interlaced image this is the best approach; read each row of each pass,
2327transform it, and write it out to a new interlaced image.
2328
2329If you want to de-interlace the image yourself libpng provides further
2330macros to help that tell you where to place the pixels in the output image.
2331Because the interlacing scheme is rectangular - sub-image pixels are always
2332arranged on a rectangular grid - all you need to know for each pass is the
2333starting column and row in the output image of the first pixel plus the
2334spacing between each pixel.  As of libpng 1.5 there are four macros to
2335retrieve this information:
2336
2337   png_uint_32 x = PNG_PASS_START_COL(pass);
2338   png_uint_32 y = PNG_PASS_START_ROW(pass);
2339   png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass);
2340   png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass);
2341
2342These allow you to write the obvious loop:
2343
2344   png_uint_32 input_y = 0;
2345   png_uint_32 output_y = PNG_PASS_START_ROW(pass);
2346
2347   while (output_y < output_image_height)
2348   {
2349      png_uint_32 input_x = 0;
2350      png_uint_32 output_x = PNG_PASS_START_COL(pass);
2351
2352      while (output_x < output_image_width)
2353      {
2354         image[output_y][output_x] =
2355             subimage[pass][input_y][input_x++];
2356
2357         output_x += xStep;
2358      }
2359
2360      ++input_y;
2361      output_y += yStep;
2362   }
2363
2364Notice that the steps between successive output rows and columns are
2365returned as shifts.  This is possible because the pixels in the subimages
2366are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original
2367image.  In practice you may need to directly calculate the output coordinate
2368given an input coordinate.  libpng provides two further macros for this
2369purpose:
2370
2371   png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass);
2372   png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass);
2373
2374Finally a pair of macros are provided to tell you if a particular image
2375row or column appears in a given pass:
2376
2377   int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass);
2378   int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass);
2379
2380Bear in mind that you will probably also need to check the width and height
2381of the pass in addition to the above to be sure the pass even exists!
2382
2383With any luck you are convinced by now that you don't want to do your own
2384interlace handling.  In reality normally the only good reason for doing this
2385is if you are processing PNG files on a pixel-by-pixel basis and don't want
2386to load the whole file into memory when it is interlaced.
2387
2388libpng includes a test program, pngvalid, that illustrates reading and
2389writing of interlaced images.  If you can't get interlacing to work in your
2390code and don't want to leave it to libpng (the recommended approach), see
2391how pngvalid.c does it.
2392
2393Finishing a sequential read
2394
2395After you are finished reading the image through the
2396low-level interface, you can finish reading the file.
2397
2398If you want to use a different crc action for handling CRC errors in
2399chunks after the image data, you can call png_set_crc_action()
2400again at this point.
2401
2402If you are interested in comments or time, which may be stored either
2403before or after the image data, you should pass the separate png_info
2404struct if you want to keep the comments from before and after the image
2405separate.
2406
2407    png_infop end_info = png_create_info_struct(png_ptr);
2408
2409    if (!end_info)
2410    {
2411       png_destroy_read_struct(&png_ptr, &info_ptr,
2412           (png_infopp)NULL);
2413       return ERROR;
2414    }
2415
2416   png_read_end(png_ptr, end_info);
2417
2418If you are not interested, you should still call png_read_end()
2419but you can pass NULL, avoiding the need to create an end_info structure.
2420If you do this, libpng will not process any chunks after IDAT other than
2421skipping over them and perhaps (depending on whether you have called
2422png_set_crc_action) checking their CRCs while looking for the IEND chunk.
2423
2424   png_read_end(png_ptr, (png_infop)NULL);
2425
2426If you don't call png_read_end(), then your file pointer will be
2427left pointing to the first chunk after the last IDAT, which is probably
2428not what you want if you expect to read something beyond the end of
2429the PNG datastream.
2430
2431When you are done, you can free all memory allocated by libpng like this:
2432
2433   png_destroy_read_struct(&png_ptr, &info_ptr,
2434       &end_info);
2435
2436or, if you didn't create an end_info structure,
2437
2438   png_destroy_read_struct(&png_ptr, &info_ptr,
2439       (png_infopp)NULL);
2440
2441It is also possible to individually free the info_ptr members that
2442point to libpng-allocated storage with the following function:
2443
2444    png_free_data(png_ptr, info_ptr, mask, seq)
2445
2446    mask - identifies data to be freed, a mask
2447           containing the bitwise OR of one or
2448           more of
2449             PNG_FREE_PLTE, PNG_FREE_TRNS,
2450             PNG_FREE_HIST, PNG_FREE_ICCP,
2451             PNG_FREE_PCAL, PNG_FREE_ROWS,
2452             PNG_FREE_SCAL, PNG_FREE_SPLT,
2453             PNG_FREE_TEXT, PNG_FREE_UNKN,
2454           or simply PNG_FREE_ALL
2455
2456    seq  - sequence number of item to be freed
2457           (-1 for all items)
2458
2459This function may be safely called when the relevant storage has
2460already been freed, or has not yet been allocated, or was allocated
2461by the user and not by libpng,  and will in those cases do nothing.
2462The "seq" parameter is ignored if only one item of the selected data
2463type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
2464are allowed for the data type identified in the mask, such as text or
2465sPLT, only the n'th item in the structure is freed, where n is "seq".
2466
2467The default behavior is only to free data that was allocated internally
2468by libpng.  This can be changed, so that libpng will not free the data,
2469or so that it will free data that was allocated by the user with png_malloc()
2470or png_calloc() and passed in via a png_set_*() function, with
2471
2472    png_data_freer(png_ptr, info_ptr, freer, mask)
2473
2474    freer  - one of
2475               PNG_DESTROY_WILL_FREE_DATA
2476               PNG_SET_WILL_FREE_DATA
2477               PNG_USER_WILL_FREE_DATA
2478
2479    mask   - which data elements are affected
2480             same choices as in png_free_data()
2481
2482This function only affects data that has already been allocated.
2483You can call this function after reading the PNG data but before calling
2484any png_set_*() functions, to control whether the user or the png_set_*()
2485function is responsible for freeing any existing data that might be present,
2486and again after the png_set_*() functions to control whether the user
2487or png_destroy_*() is supposed to free the data.  When the user assumes
2488responsibility for libpng-allocated data, the application must use
2489png_free() to free it, and when the user transfers responsibility to libpng
2490for data that the user has allocated, the user must have used png_malloc()
2491or png_calloc() to allocate it.
2492
2493If you allocated your row_pointers in a single block, as suggested above in
2494the description of the high level read interface, you must not transfer
2495responsibility for freeing it to the png_set_rows or png_read_destroy function,
2496because they would also try to free the individual row_pointers[i].
2497
2498If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2499separately, do not transfer responsibility for freeing text_ptr to libpng,
2500because when libpng fills a png_text structure it combines these members with
2501the key member, and png_free_data() will free only text_ptr.key.  Similarly,
2502if you transfer responsibility for free'ing text_ptr from libpng to your
2503application, your application must not separately free those members.
2504
2505The png_free_data() function will turn off the "valid" flag for anything
2506it frees.  If you need to turn the flag off for a chunk that was freed by
2507your application instead of by libpng, you can use
2508
2509    png_set_invalid(png_ptr, info_ptr, mask);
2510
2511    mask - identifies the chunks to be made invalid,
2512           containing the bitwise OR of one or
2513           more of
2514             PNG_INFO_gAMA, PNG_INFO_sBIT,
2515             PNG_INFO_cHRM, PNG_INFO_PLTE,
2516             PNG_INFO_tRNS, PNG_INFO_bKGD,
2517             PNG_INFO_eXIf,
2518             PNG_INFO_hIST, PNG_INFO_pHYs,
2519             PNG_INFO_oFFs, PNG_INFO_tIME,
2520             PNG_INFO_pCAL, PNG_INFO_sRGB,
2521             PNG_INFO_iCCP, PNG_INFO_sPLT,
2522             PNG_INFO_sCAL, PNG_INFO_IDAT
2523
2524For a more compact example of reading a PNG image, see the file example.c.
2525
2526Reading PNG files progressively
2527
2528The progressive reader is slightly different from the non-progressive
2529reader.  Instead of calling png_read_info(), png_read_rows(), and
2530png_read_end(), you make one call to png_process_data(), which calls
2531callbacks when it has the info, a row, or the end of the image.  You
2532set up these callbacks with png_set_progressive_read_fn().  You don't
2533have to worry about the input/output functions of libpng, as you are
2534giving the library the data directly in png_process_data().  I will
2535assume that you have read the section on reading PNG files above,
2536so I will only highlight the differences (although I will show
2537all of the code).
2538
2539png_structp png_ptr;
2540png_infop info_ptr;
2541
2542 /*  An example code fragment of how you would
2543     initialize the progressive reader in your
2544     application. */
2545 int
2546 initialize_png_reader()
2547 {
2548    png_ptr = png_create_read_struct
2549        (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2550         user_error_fn, user_warning_fn);
2551
2552    if (!png_ptr)
2553        return ERROR;
2554
2555    info_ptr = png_create_info_struct(png_ptr);
2556
2557    if (!info_ptr)
2558    {
2559       png_destroy_read_struct(&png_ptr,
2560          (png_infopp)NULL, (png_infopp)NULL);
2561       return ERROR;
2562    }
2563
2564    if (setjmp(png_jmpbuf(png_ptr)))
2565    {
2566       png_destroy_read_struct(&png_ptr, &info_ptr,
2567          (png_infopp)NULL);
2568       return ERROR;
2569    }
2570
2571    /* This one's new.  You can provide functions
2572       to be called when the header info is valid,
2573       when each row is completed, and when the image
2574       is finished.  If you aren't using all functions,
2575       you can specify NULL parameters.  Even when all
2576       three functions are NULL, you need to call
2577       png_set_progressive_read_fn().  You can use
2578       any struct as the user_ptr (cast to a void pointer
2579       for the function call), and retrieve the pointer
2580       from inside the callbacks using the function
2581
2582          png_get_progressive_ptr(png_ptr);
2583
2584       which will return a void pointer, which you have
2585       to cast appropriately.
2586     */
2587    png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2588        info_callback, row_callback, end_callback);
2589
2590    return 0;
2591 }
2592
2593 /* A code fragment that you call as you receive blocks
2594   of data */
2595 int
2596 process_data(png_bytep buffer, png_uint_32 length)
2597 {
2598    if (setjmp(png_jmpbuf(png_ptr)))
2599    {
2600       png_destroy_read_struct(&png_ptr, &info_ptr,
2601           (png_infopp)NULL);
2602       return ERROR;
2603    }
2604
2605    /* This one's new also.  Simply give it a chunk
2606       of data from the file stream (in order, of
2607       course).  On machines with segmented memory
2608       models machines, don't give it any more than
2609       64K.  The library seems to run fine with sizes
2610       of 4K. Although you can give it much less if
2611       necessary (I assume you can give it chunks of
2612       1 byte, I haven't tried less than 256 bytes
2613       yet).  When this function returns, you may
2614       want to display any rows that were generated
2615       in the row callback if you don't already do
2616       so there.
2617     */
2618    png_process_data(png_ptr, info_ptr, buffer, length);
2619
2620    /* At this point you can call png_process_data_skip if
2621       you want to handle data the library will skip yourself;
2622       it simply returns the number of bytes to skip (and stops
2623       libpng skipping that number of bytes on the next
2624       png_process_data call).
2625    return 0;
2626 }
2627
2628 /* This function is called (as set by
2629    png_set_progressive_read_fn() above) when enough data
2630    has been supplied so all of the header has been
2631    read.
2632 */
2633 void
2634 info_callback(png_structp png_ptr, png_infop info)
2635 {
2636    /* Do any setup here, including setting any of
2637       the transformations mentioned in the Reading
2638       PNG files section.  For now, you _must_ call
2639       either png_start_read_image() or
2640       png_read_update_info() after all the
2641       transformations are set (even if you don't set
2642       any).  You may start getting rows before
2643       png_process_data() returns, so this is your
2644       last chance to prepare for that.
2645
2646       This is where you turn on interlace handling,
2647       assuming you don't want to do it yourself.
2648
2649       If you need to you can stop the processing of
2650       your original input data at this point by calling
2651       png_process_data_pause.  This returns the number
2652       of unprocessed bytes from the last png_process_data
2653       call - it is up to you to ensure that the next call
2654       sees these bytes again.  If you don't want to bother
2655       with this you can get libpng to cache the unread
2656       bytes by setting the 'save' parameter (see png.h) but
2657       then libpng will have to copy the data internally.
2658     */
2659 }
2660
2661 /* This function is called when each row of image
2662    data is complete */
2663 void
2664 row_callback(png_structp png_ptr, png_bytep new_row,
2665    png_uint_32 row_num, int pass)
2666 {
2667    /* If the image is interlaced, and you turned
2668       on the interlace handler, this function will
2669       be called for every row in every pass.  Some
2670       of these rows will not be changed from the
2671       previous pass.  When the row is not changed,
2672       the new_row variable will be NULL.  The rows
2673       and passes are called in order, so you don't
2674       really need the row_num and pass, but I'm
2675       supplying them because it may make your life
2676       easier.
2677
2678       If you did not turn on interlace handling then
2679       the callback is called for each row of each
2680       sub-image when the image is interlaced.  In this
2681       case 'row_num' is the row in the sub-image, not
2682       the row in the output image as it is in all other
2683       cases.
2684
2685       For the non-NULL rows of interlaced images when
2686       you have switched on libpng interlace handling,
2687       you must call png_progressive_combine_row()
2688       passing in the row and the old row.  You can
2689       call this function for NULL rows (it will just
2690       return) and for non-interlaced images (it just
2691       does the memcpy for you) if it will make the
2692       code easier.  Thus, you can just do this for
2693       all cases if you switch on interlace handling;
2694     */
2695
2696        png_progressive_combine_row(png_ptr, old_row,
2697          new_row);
2698
2699    /* where old_row is what was displayed
2700       previously for the row.  Note that the first
2701       pass (pass == 0, really) will completely cover
2702       the old row, so the rows do not have to be
2703       initialized.  After the first pass (and only
2704       for interlaced images), you will have to pass
2705       the current row, and the function will combine
2706       the old row and the new row.
2707
2708       You can also call png_process_data_pause in this
2709       callback - see above.
2710    */
2711 }
2712
2713 void
2714 end_callback(png_structp png_ptr, png_infop info)
2715 {
2716    /* This function is called after the whole image
2717       has been read, including any chunks after the
2718       image (up to and including the IEND).  You
2719       will usually have the same info chunk as you
2720       had in the header, although some data may have
2721       been added to the comments and time fields.
2722
2723       Most people won't do much here, perhaps setting
2724       a flag that marks the image as finished.
2725     */
2726 }
2727
2728
2729
2730IV. Writing
2731
2732Much of this is very similar to reading.  However, everything of
2733importance is repeated here, so you won't have to constantly look
2734back up in the reading section to understand writing.
2735
2736Setup
2737
2738You will want to do the I/O initialization before you get into libpng,
2739so if it doesn't work, you don't have anything to undo. If you are not
2740using the standard I/O functions, you will need to replace them with
2741custom writing functions.  See the discussion under Customizing libpng.
2742
2743    FILE *fp = fopen(file_name, "wb");
2744
2745    if (!fp)
2746       return ERROR;
2747
2748Next, png_struct and png_info need to be allocated and initialized.
2749As these can be both relatively large, you may not want to store these
2750on the stack, unless you have stack space to spare.  Of course, you
2751will want to check if they return NULL.  If you are also reading,
2752you won't want to name your read structure and your write structure
2753both "png_ptr"; you can call them anything you like, such as
2754"read_ptr" and "write_ptr".  Look at pngtest.c, for example.
2755
2756    png_structp png_ptr = png_create_write_struct
2757       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2758        user_error_fn, user_warning_fn);
2759
2760    if (!png_ptr)
2761       return ERROR;
2762
2763    png_infop info_ptr = png_create_info_struct(png_ptr);
2764    if (!info_ptr)
2765    {
2766       png_destroy_write_struct(&png_ptr,
2767           (png_infopp)NULL);
2768       return ERROR;
2769    }
2770
2771If you want to use your own memory allocation routines,
2772define PNG_USER_MEM_SUPPORTED and use
2773png_create_write_struct_2() instead of png_create_write_struct():
2774
2775    png_structp png_ptr = png_create_write_struct_2
2776       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2777        user_error_fn, user_warning_fn, (png_voidp)
2778        user_mem_ptr, user_malloc_fn, user_free_fn);
2779
2780After you have these structures, you will need to set up the
2781error handling.  When libpng encounters an error, it expects to
2782longjmp() back to your routine.  Therefore, you will need to call
2783setjmp() and pass the png_jmpbuf(png_ptr).  If you
2784write the file from different routines, you will need to update
2785the png_jmpbuf(png_ptr) every time you enter a new routine that will
2786call a png_*() function.  See your documentation of setjmp/longjmp
2787for your compiler for more information on setjmp/longjmp.  See
2788the discussion on libpng error handling in the Customizing Libpng
2789section below for more information on the libpng error handling.
2790
2791    if (setjmp(png_jmpbuf(png_ptr)))
2792    {
2793    png_destroy_write_struct(&png_ptr, &info_ptr);
2794       fclose(fp);
2795       return ERROR;
2796    }
2797    ...
2798    return;
2799
2800If you would rather avoid the complexity of setjmp/longjmp issues,
2801you can compile libpng with PNG_NO_SETJMP, in which case
2802errors will result in a call to PNG_ABORT() which defaults to abort().
2803
2804You can #define PNG_ABORT() to a function that does something
2805more useful than abort(), as long as your function does not
2806return.
2807
2808Checking for invalid palette index on write was added at libpng
28091.5.10.  If a pixel contains an invalid (out-of-range) index libpng issues
2810a benign error.  This is enabled by default because this condition is an
2811error according to the PNG specification, Clause 11.3.2, but the error can
2812be ignored in each png_ptr with
2813
2814   png_set_check_for_invalid_index(png_ptr, 0);
2815
2816If the error is ignored, or if png_benign_error() treats it as a warning,
2817any invalid pixels are written as-is by the encoder, resulting in an
2818invalid PNG datastream as output.  In this case the application is
2819responsible for ensuring that the pixel indexes are in range when it writes
2820a PLTE chunk with fewer entries than the bit depth would allow.
2821
2822Now you need to set up the output code.  The default for libpng is to
2823use the C function fwrite().  If you use this, you will need to pass a
2824valid FILE * in the function png_init_io().  Be sure that the file is
2825opened in binary mode.  Again, if you wish to handle writing data in
2826another way, see the discussion on libpng I/O handling in the Customizing
2827Libpng section below.
2828
2829    png_init_io(png_ptr, fp);
2830
2831If you are embedding your PNG into a datastream such as MNG, and don't
2832want libpng to write the 8-byte signature, or if you have already
2833written the signature in your application, use
2834
2835    png_set_sig_bytes(png_ptr, 8);
2836
2837to inform libpng that it should not write a signature.
2838
2839Write callbacks
2840
2841At this point, you can set up a callback function that will be
2842called after each row has been written, which you can use to control
2843a progress meter or the like.  It's demonstrated in pngtest.c.
2844You must supply a function
2845
2846    void write_row_callback(png_structp png_ptr, png_uint_32 row,
2847       int pass);
2848    {
2849      /* put your code here */
2850    }
2851
2852(You can give it another name that you like instead of "write_row_callback")
2853
2854To inform libpng about your function, use
2855
2856    png_set_write_status_fn(png_ptr, write_row_callback);
2857
2858When this function is called the row has already been completely processed and
2859it has also been written out.  The 'row' and 'pass' refer to the next row to be
2860handled.  For the
2861non-interlaced case the row that was just handled is simply one less than the
2862passed in row number, and pass will always be 0.  For the interlaced case the
2863same applies unless the row value is 0, in which case the row just handled was
2864the last one from one of the preceding passes.  Because interlacing may skip a
2865pass you cannot be sure that the preceding pass is just 'pass-1', if you really
2866need to know what the last pass is record (row,pass) from the callback and use
2867the last recorded value each time.
2868
2869As with the user transform you can find the output row using the
2870PNG_ROW_FROM_PASS_ROW macro.
2871
2872You now have the option of modifying how the compression library will
2873run.  The following functions are mainly for testing, but may be useful
2874in some cases, like if you need to write PNG files extremely fast and
2875are willing to give up some compression, or if you want to get the
2876maximum possible compression at the expense of slower writing.  If you
2877have no special needs in this area, let the library do what it wants by
2878not calling this function at all, as it has been tuned to deliver a good
2879speed/compression ratio. The second parameter to png_set_filter() is
2880the filter method, for which the only valid values are 0 (as of the
2881July 1999 PNG specification, version 1.2) or 64 (if you are writing
2882a PNG datastream that is to be embedded in a MNG datastream).  The third
2883parameter is a flag that indicates which filter type(s) are to be tested
2884for each scanline.  See the PNG specification for details on the specific
2885filter types.
2886
2887
2888    /* turn on or off filtering, and/or choose
2889       specific filters.  You can use either a single
2890       PNG_FILTER_VALUE_NAME or the bitwise OR of one
2891       or more PNG_FILTER_NAME masks.
2892     */
2893    png_set_filter(png_ptr, 0,
2894       PNG_FILTER_NONE  | PNG_FILTER_VALUE_NONE |
2895       PNG_FILTER_SUB   | PNG_FILTER_VALUE_SUB  |
2896       PNG_FILTER_UP    | PNG_FILTER_VALUE_UP   |
2897       PNG_FILTER_AVG   | PNG_FILTER_VALUE_AVG  |
2898       PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2899       PNG_ALL_FILTERS  | PNG_FAST_FILTERS);
2900
2901If an application wants to start and stop using particular filters during
2902compression, it should start out with all of the filters (to ensure that
2903the previous row of pixels will be stored in case it's needed later),
2904and then add and remove them after the start of compression.
2905
2906If you are writing a PNG datastream that is to be embedded in a MNG
2907datastream, the second parameter can be either 0 or 64.
2908
2909The png_set_compression_*() functions interface to the zlib compression
2910library, and should mostly be ignored unless you really know what you are
2911doing.  The only generally useful call is png_set_compression_level()
2912which changes how much time zlib spends on trying to compress the image
2913data.  See the Compression Library (zlib.h and algorithm.txt, distributed
2914with zlib) for details on the compression levels.
2915
2916    #include zlib.h
2917
2918    /* Set the zlib compression level */
2919    png_set_compression_level(png_ptr,
2920        Z_BEST_COMPRESSION);
2921
2922    /* Set other zlib parameters for compressing IDAT */
2923    png_set_compression_mem_level(png_ptr, 8);
2924    png_set_compression_strategy(png_ptr,
2925        Z_DEFAULT_STRATEGY);
2926    png_set_compression_window_bits(png_ptr, 15);
2927    png_set_compression_method(png_ptr, 8);
2928    png_set_compression_buffer_size(png_ptr, 8192)
2929
2930    /* Set zlib parameters for text compression
2931     * If you don't call these, the parameters
2932     * fall back on those defined for IDAT chunks
2933     */
2934    png_set_text_compression_mem_level(png_ptr, 8);
2935    png_set_text_compression_strategy(png_ptr,
2936        Z_DEFAULT_STRATEGY);
2937    png_set_text_compression_window_bits(png_ptr, 15);
2938    png_set_text_compression_method(png_ptr, 8);
2939
2940Setting the contents of info for output
2941
2942You now need to fill in the png_info structure with all the data you
2943wish to write before the actual image.  Note that the only thing you
2944are allowed to write after the image is the text chunks and the time
2945chunk (as of PNG Specification 1.2, anyway).  See png_write_end() and
2946the latest PNG specification for more information on that.  If you
2947wish to write them before the image, fill them in now, and flag that
2948data as being valid.  If you want to wait until after the data, don't
2949fill them until png_write_end().  For all the fields in png_info and
2950their data types, see png.h.  For explanations of what the fields
2951contain, see the PNG specification.
2952
2953Some of the more important parts of the png_info are:
2954
2955    png_set_IHDR(png_ptr, info_ptr, width, height,
2956       bit_depth, color_type, interlace_type,
2957       compression_type, filter_method)
2958
2959    width          - holds the width of the image
2960                     in pixels (up to 2^31).
2961
2962    height         - holds the height of the image
2963                     in pixels (up to 2^31).
2964
2965    bit_depth      - holds the bit depth of one of the
2966                     image channels.
2967                     (valid values are 1, 2, 4, 8, 16
2968                     and depend also on the
2969                     color_type.  See also significant
2970                     bits (sBIT) below).
2971
2972    color_type     - describes which color/alpha
2973                     channels are present.
2974                     PNG_COLOR_TYPE_GRAY
2975                        (bit depths 1, 2, 4, 8, 16)
2976                     PNG_COLOR_TYPE_GRAY_ALPHA
2977                        (bit depths 8, 16)
2978                     PNG_COLOR_TYPE_PALETTE
2979                        (bit depths 1, 2, 4, 8)
2980                     PNG_COLOR_TYPE_RGB
2981                        (bit_depths 8, 16)
2982                     PNG_COLOR_TYPE_RGB_ALPHA
2983                        (bit_depths 8, 16)
2984
2985                     PNG_COLOR_MASK_PALETTE
2986                     PNG_COLOR_MASK_COLOR
2987                     PNG_COLOR_MASK_ALPHA
2988
2989    interlace_type - PNG_INTERLACE_NONE or
2990                     PNG_INTERLACE_ADAM7
2991
2992    compression_type - (must be
2993                     PNG_COMPRESSION_TYPE_DEFAULT)
2994
2995    filter_method  - (must be PNG_FILTER_TYPE_DEFAULT
2996                     or, if you are writing a PNG to
2997                     be embedded in a MNG datastream,
2998                     can also be
2999                     PNG_INTRAPIXEL_DIFFERENCING)
3000
3001If you call png_set_IHDR(), the call must appear before any of the
3002other png_set_*() functions, because they might require access to some of
3003the IHDR settings.  The remaining png_set_*() functions can be called
3004in any order.
3005
3006If you wish, you can reset the compression_type, interlace_type, or
3007filter_method later by calling png_set_IHDR() again; if you do this, the
3008width, height, bit_depth, and color_type must be the same in each call.
3009
3010    png_set_PLTE(png_ptr, info_ptr, palette,
3011       num_palette);
3012
3013    palette        - the palette for the file
3014                     (array of png_color)
3015    num_palette    - number of entries in the palette
3016
3017
3018    png_set_gAMA(png_ptr, info_ptr, file_gamma);
3019    png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma);
3020
3021    file_gamma     - the gamma at which the image was
3022                     created (PNG_INFO_gAMA)
3023
3024    int_file_gamma - 100,000 times the gamma at which
3025                     the image was created
3026
3027    png_set_cHRM(png_ptr, info_ptr,  white_x, white_y, red_x, red_y,
3028                     green_x, green_y, blue_x, blue_y)
3029    png_set_cHRM_XYZ(png_ptr, info_ptr, red_X, red_Y, red_Z, green_X,
3030                     green_Y, green_Z, blue_X, blue_Y, blue_Z)
3031    png_set_cHRM_fixed(png_ptr, info_ptr, int_white_x, int_white_y,
3032                     int_red_x, int_red_y, int_green_x, int_green_y,
3033                     int_blue_x, int_blue_y)
3034    png_set_cHRM_XYZ_fixed(png_ptr, info_ptr, int_red_X, int_red_Y,
3035                     int_red_Z, int_green_X, int_green_Y, int_green_Z,
3036                     int_blue_X, int_blue_Y, int_blue_Z)
3037
3038    {white,red,green,blue}_{x,y}
3039                     A color space encoding specified using the chromaticities
3040                     of the end points and the white point.
3041
3042    {red,green,blue}_{X,Y,Z}
3043                     A color space encoding specified using the encoding end
3044                     points - the CIE tristimulus specification of the intended
3045                     color of the red, green and blue channels in the PNG RGB
3046                     data.  The white point is simply the sum of the three end
3047                     points.
3048
3049    png_set_sRGB(png_ptr, info_ptr, srgb_intent);
3050
3051    srgb_intent    - the rendering intent
3052                     (PNG_INFO_sRGB) The presence of
3053                     the sRGB chunk means that the pixel
3054                     data is in the sRGB color space.
3055                     This chunk also implies specific
3056                     values of gAMA and cHRM.  Rendering
3057                     intent is the CSS-1 property that
3058                     has been defined by the International
3059                     Color Consortium
3060                     (http://www.color.org).
3061                     It can be one of
3062                     PNG_sRGB_INTENT_SATURATION,
3063                     PNG_sRGB_INTENT_PERCEPTUAL,
3064                     PNG_sRGB_INTENT_ABSOLUTE, or
3065                     PNG_sRGB_INTENT_RELATIVE.
3066
3067
3068    png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
3069       srgb_intent);
3070
3071    srgb_intent    - the rendering intent
3072                     (PNG_INFO_sRGB) The presence of the
3073                     sRGB chunk means that the pixel
3074                     data is in the sRGB color space.
3075                     This function also causes gAMA and
3076                     cHRM chunks with the specific values
3077                     that are consistent with sRGB to be
3078                     written.
3079
3080    png_set_iCCP(png_ptr, info_ptr, name, compression_type,
3081                       profile, proflen);
3082
3083    name             - The profile name.
3084
3085    compression_type - The compression type; always
3086                       PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
3087                       You may give NULL to this argument to
3088                       ignore it.
3089
3090    profile          - International Color Consortium color
3091                       profile data. May contain NULs.
3092
3093    proflen          - length of profile data in bytes.
3094
3095    png_set_sBIT(png_ptr, info_ptr, sig_bit);
3096
3097    sig_bit        - the number of significant bits for
3098                     (PNG_INFO_sBIT) each of the gray, red,
3099                     green, and blue channels, whichever are
3100                     appropriate for the given color type
3101                     (png_color_16)
3102
3103    png_set_tRNS(png_ptr, info_ptr, trans_alpha,
3104       num_trans, trans_color);
3105
3106    trans_alpha    - array of alpha (transparency)
3107                     entries for palette (PNG_INFO_tRNS)
3108
3109    num_trans      - number of transparent entries
3110                     (PNG_INFO_tRNS)
3111
3112    trans_color    - graylevel or color sample values
3113                     (in order red, green, blue) of the
3114                     single transparent color for
3115                     non-paletted images (PNG_INFO_tRNS)
3116
3117    png_set_eXIf_1(png_ptr, info_ptr, num_exif, exif);
3118
3119    exif           - Exif profile (array of
3120                     png_byte) (PNG_INFO_eXIf)
3121
3122    png_set_hIST(png_ptr, info_ptr, hist);
3123
3124    hist           - histogram of palette (array of
3125                     png_uint_16) (PNG_INFO_hIST)
3126
3127    png_set_tIME(png_ptr, info_ptr, mod_time);
3128
3129    mod_time       - time image was last modified
3130                     (PNG_VALID_tIME)
3131
3132    png_set_bKGD(png_ptr, info_ptr, background);
3133
3134    background     - background color (of type
3135                     png_color_16p) (PNG_VALID_bKGD)
3136
3137    png_set_text(png_ptr, info_ptr, text_ptr, num_text);
3138
3139    text_ptr       - array of png_text holding image
3140                     comments
3141
3142    text_ptr[i].compression - type of compression used
3143                 on "text" PNG_TEXT_COMPRESSION_NONE
3144                           PNG_TEXT_COMPRESSION_zTXt
3145                           PNG_ITXT_COMPRESSION_NONE
3146                           PNG_ITXT_COMPRESSION_zTXt
3147    text_ptr[i].key   - keyword for comment.  Must contain
3148                 1-79 characters.
3149    text_ptr[i].text  - text comments for current
3150                         keyword.  Can be NULL or empty.
3151    text_ptr[i].text_length - length of text string,
3152                 after decompression, 0 for iTXt
3153    text_ptr[i].itxt_length - length of itxt string,
3154                 after decompression, 0 for tEXt/zTXt
3155    text_ptr[i].lang  - language of comment (NULL or
3156                         empty for unknown).
3157    text_ptr[i].translated_keyword  - keyword in UTF-8 (NULL
3158                         or empty for unknown).
3159
3160    Note that the itxt_length, lang, and lang_key
3161    members of the text_ptr structure only exist when the
3162    library is built with iTXt chunk support.  Prior to
3163    libpng-1.4.0 the library was built by default without
3164    iTXt support. Also note that when iTXt is supported,
3165    they contain NULL pointers when the "compression"
3166    field contains PNG_TEXT_COMPRESSION_NONE or
3167    PNG_TEXT_COMPRESSION_zTXt.
3168
3169    num_text       - number of comments
3170
3171    png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
3172       num_spalettes);
3173
3174    palette_ptr    - array of png_sPLT_struct structures
3175                     to be added to the list of palettes
3176                     in the info structure.
3177    num_spalettes  - number of palette structures to be
3178                     added.
3179
3180    png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
3181        unit_type);
3182
3183    offset_x  - positive offset from the left
3184                     edge of the screen
3185
3186    offset_y  - positive offset from the top
3187                     edge of the screen
3188
3189    unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
3190
3191    png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
3192        unit_type);
3193
3194    res_x       - pixels/unit physical resolution
3195                  in x direction
3196
3197    res_y       - pixels/unit physical resolution
3198                  in y direction
3199
3200    unit_type   - PNG_RESOLUTION_UNKNOWN,
3201                  PNG_RESOLUTION_METER
3202
3203    png_set_sCAL(png_ptr, info_ptr, unit, width, height)
3204
3205    unit        - physical scale units (an integer)
3206
3207    width       - width of a pixel in physical scale units
3208
3209    height      - height of a pixel in physical scale units
3210                  (width and height are doubles)
3211
3212    png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
3213
3214    unit        - physical scale units (an integer)
3215
3216    width       - width of a pixel in physical scale units
3217                  expressed as a string
3218
3219    height      - height of a pixel in physical scale units
3220                 (width and height are strings like "2.54")
3221
3222    png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
3223       num_unknowns)
3224
3225    unknowns          - array of png_unknown_chunk
3226                        structures holding unknown chunks
3227    unknowns[i].name  - name of unknown chunk
3228    unknowns[i].data  - data of unknown chunk
3229    unknowns[i].size  - size of unknown chunk's data
3230    unknowns[i].location - position to write chunk in file
3231                           0: do not write chunk
3232                           PNG_HAVE_IHDR: before PLTE
3233                           PNG_HAVE_PLTE: before IDAT
3234                           PNG_AFTER_IDAT: after IDAT
3235
3236The "location" member is set automatically according to
3237what part of the output file has already been written.
3238You can change its value after calling png_set_unknown_chunks()
3239as demonstrated in pngtest.c.  Within each of the "locations",
3240the chunks are sequenced according to their position in the
3241structure (that is, the value of "i", which is the order in which
3242the chunk was either read from the input file or defined with
3243png_set_unknown_chunks).
3244
3245A quick word about text and num_text.  text is an array of png_text
3246structures.  num_text is the number of valid structures in the array.
3247Each png_text structure holds a language code, a keyword, a text value,
3248and a compression type.
3249
3250The compression types have the same valid numbers as the compression
3251types of the image data.  Currently, the only valid number is zero.
3252However, you can store text either compressed or uncompressed, unlike
3253images, which always have to be compressed.  So if you don't want the
3254text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
3255Because tEXt and zTXt chunks don't have a language field, if you
3256specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
3257any language code or translated keyword will not be written out.
3258
3259Until text gets around a few hundred bytes, it is not worth compressing it.
3260After the text has been written out to the file, the compression type
3261is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
3262so that it isn't written out again at the end (in case you are calling
3263png_write_end() with the same struct).
3264
3265The keywords that are given in the PNG Specification are:
3266
3267    Title            Short (one line) title or
3268                     caption for image
3269
3270    Author           Name of image's creator
3271
3272    Description      Description of image (possibly long)
3273
3274    Copyright        Copyright notice
3275
3276    Creation Time    Time of original image creation
3277                     (usually RFC 1123 format, see below)
3278
3279    Software         Software used to create the image
3280
3281    Disclaimer       Legal disclaimer
3282
3283    Warning          Warning of nature of content
3284
3285    Source           Device used to create the image
3286
3287    Comment          Miscellaneous comment; conversion
3288                     from other image format
3289
3290The keyword-text pairs work like this.  Keywords should be short
3291simple descriptions of what the comment is about.  Some typical
3292keywords are found in the PNG specification, as is some recommendations
3293on keywords.  You can repeat keywords in a file.  You can even write
3294some text before the image and some after.  For example, you may want
3295to put a description of the image before the image, but leave the
3296disclaimer until after, so viewers working over modem connections
3297don't have to wait for the disclaimer to go over the modem before
3298they start seeing the image.  Finally, keywords should be full
3299words, not abbreviations.  Keywords and text are in the ISO 8859-1
3300(Latin-1) character set (a superset of regular ASCII) and can not
3301contain NUL characters, and should not contain control or other
3302unprintable characters.  To make the comments widely readable, stick
3303with basic ASCII, and avoid machine specific character set extensions
3304like the IBM-PC character set.  The keyword must be present, but
3305you can leave off the text string on non-compressed pairs.
3306Compressed pairs must have a text string, as only the text string
3307is compressed anyway, so the compression would be meaningless.
3308
3309PNG supports modification time via the png_time structure.  Two
3310conversion routines are provided, png_convert_from_time_t() for
3311time_t and png_convert_from_struct_tm() for struct tm.  The
3312time_t routine uses gmtime().  You don't have to use either of
3313these, but if you wish to fill in the png_time structure directly,
3314you should provide the time in universal time (GMT) if possible
3315instead of your local time.  Note that the year number is the full
3316year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
3317that months start with 1.
3318
3319If you want to store the time of the original image creation, you should
3320use a plain tEXt chunk with the "Creation Time" keyword.  This is
3321necessary because the "creation time" of a PNG image is somewhat vague,
3322depending on whether you mean the PNG file, the time the image was
3323created in a non-PNG format, a still photo from which the image was
3324scanned, or possibly the subject matter itself.  In order to facilitate
3325machine-readable dates, it is recommended that the "Creation Time"
3326tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
3327although this isn't a requirement.  Unlike the tIME chunk, the
3328"Creation Time" tEXt chunk is not expected to be automatically changed
3329by the software.  To facilitate the use of RFC 1123 dates, a function
3330png_convert_to_rfc1123_buffer(buffer, png_timep) is provided to
3331convert from PNG time to an RFC 1123 format string.  The caller must provide
3332a writeable buffer of at least 29 bytes.
3333
3334Writing unknown chunks
3335
3336You can use the png_set_unknown_chunks function to queue up private chunks
3337for writing.  You give it a chunk name, location, raw data, and a size.  You
3338also must use png_set_keep_unknown_chunks() to ensure that libpng will
3339handle them.  That's all there is to it.  The chunks will be written by the
3340next following png_write_info_before_PLTE, png_write_info, or png_write_end
3341function, depending upon the specified location.  Any chunks previously
3342read into the info structure's unknown-chunk list will also be written out
3343in a sequence that satisfies the PNG specification's ordering rules.
3344
3345Here is an example of writing two private chunks, prVt and miNE:
3346
3347    #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED
3348    /* Set unknown chunk data */
3349    png_unknown_chunk unk_chunk[2];
3350    strcpy((char *) unk_chunk[0].name, "prVt";
3351    unk_chunk[0].data = (unsigned char *) "PRIVATE DATA";
3352    unk_chunk[0].size = strlen(unk_chunk[0].data)+1;
3353    unk_chunk[0].location = PNG_HAVE_IHDR;
3354    strcpy((char *) unk_chunk[1].name, "miNE";
3355    unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA";
3356    unk_chunk[1].size = strlen(unk_chunk[0].data)+1;
3357    unk_chunk[1].location = PNG_AFTER_IDAT;
3358    png_set_unknown_chunks(write_ptr, write_info_ptr,
3359        unk_chunk, 2);
3360    /* Needed because miNE is not safe-to-copy */
3361    png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS,
3362       (png_bytep) "miNE", 1);
3363    # if PNG_LIBPNG_VER < 10600
3364      /* Deal with unknown chunk location bug in 1.5.x and earlier */
3365      png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR);
3366      png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT);
3367    # endif
3368    # if PNG_LIBPNG_VER < 10500
3369      /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0,
3370       * one before IDAT and another after IDAT, so don't use it; only use
3371       * PNG_HAVE_IHDR location.  This call resets the location previously
3372       * set by assignment and png_set_unknown_chunk_location() for chunk 1.
3373       */
3374      png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR);
3375    # endif
3376    #endif
3377
3378The high-level write interface
3379
3380At this point there are two ways to proceed; through the high-level
3381write interface, or through a sequence of low-level write operations.
3382You can use the high-level interface if your image data is present
3383in the info structure.  All defined output
3384transformations are permitted, enabled by the following masks.
3385
3386    PNG_TRANSFORM_IDENTITY      No transformation
3387    PNG_TRANSFORM_PACKING       Pack 1, 2 and 4-bit samples
3388    PNG_TRANSFORM_PACKSWAP      Change order of packed
3389                                pixels to LSB first
3390    PNG_TRANSFORM_INVERT_MONO   Invert monochrome images
3391    PNG_TRANSFORM_SHIFT         Normalize pixels to the
3392                                sBIT depth
3393    PNG_TRANSFORM_BGR           Flip RGB to BGR, RGBA
3394                                to BGRA
3395    PNG_TRANSFORM_SWAP_ALPHA    Flip RGBA to ARGB or GA
3396                                to AG
3397    PNG_TRANSFORM_INVERT_ALPHA  Change alpha from opacity
3398                                to transparency
3399    PNG_TRANSFORM_SWAP_ENDIAN   Byte-swap 16-bit samples
3400    PNG_TRANSFORM_STRIP_FILLER        Strip out filler
3401                                      bytes (deprecated).
3402    PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
3403                                      filler bytes
3404    PNG_TRANSFORM_STRIP_FILLER_AFTER  Strip out trailing
3405                                      filler bytes
3406
3407If you have valid image data in the info structure (you can use
3408png_set_rows() to put image data in the info structure), simply do this:
3409
3410    png_write_png(png_ptr, info_ptr, png_transforms, NULL)
3411
3412where png_transforms is an integer containing the bitwise OR of some set of
3413transformation flags.  This call is equivalent to png_write_info(),
3414followed the set of transformations indicated by the transform mask,
3415then png_write_image(), and finally png_write_end().
3416
3417(The final parameter of this call is not yet used.  Someday it might point
3418to transformation parameters required by some future output transform.)
3419
3420You must use png_transforms and not call any png_set_transform() functions
3421when you use png_write_png().
3422
3423The low-level write interface
3424
3425If you are going the low-level route instead, you are now ready to
3426write all the file information up to the actual image data.  You do
3427this with a call to png_write_info().
3428
3429    png_write_info(png_ptr, info_ptr);
3430
3431Note that there is one transformation you may need to do before
3432png_write_info().  In PNG files, the alpha channel in an image is the
3433level of opacity.  If your data is supplied as a level of transparency,
3434you can invert the alpha channel before you write it, so that 0 is
3435fully transparent and 255 (in 8-bit or paletted images) or 65535
3436(in 16-bit images) is fully opaque, with
3437
3438    png_set_invert_alpha(png_ptr);
3439
3440This must appear before png_write_info() instead of later with the
3441other transformations because in the case of paletted images the tRNS
3442chunk data has to be inverted before the tRNS chunk is written.  If
3443your image is not a paletted image, the tRNS data (which in such cases
3444represents a single color to be rendered as transparent) won't need to
3445be changed, and you can safely do this transformation after your
3446png_write_info() call.
3447
3448If you need to write a private chunk that you want to appear before
3449the PLTE chunk when PLTE is present, you can write the PNG info in
3450two steps, and insert code to write your own chunk between them:
3451
3452    png_write_info_before_PLTE(png_ptr, info_ptr);
3453    png_set_unknown_chunks(png_ptr, info_ptr, ...);
3454    png_write_info(png_ptr, info_ptr);
3455
3456After you've written the file information, you can set up the library
3457to handle any special transformations of the image data.  The various
3458ways to transform the data will be described in the order that they
3459should occur.  This is important, as some of these change the color
3460type and/or bit depth of the data, and some others only work on
3461certain color types and bit depths.  Even though each transformation
3462checks to see if it has data that it can do something with, you should
3463make sure to only enable a transformation if it will be valid for the
3464data.  For example, don't swap red and blue on grayscale data.
3465
3466PNG files store RGB pixels packed into 3 or 6 bytes.  This code tells
3467the library to strip input data that has 4 or 8 bytes per pixel down
3468to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
3469bytes per pixel).
3470
3471    png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
3472
3473where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
3474PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
3475is stored XRGB or RGBX.
3476
3477PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
3478they can, resulting in, for example, 8 pixels per byte for 1 bit files.
3479If the data is supplied at 1 pixel per byte, use this code, which will
3480correctly pack the pixels into a single byte:
3481
3482    png_set_packing(png_ptr);
3483
3484PNG files reduce possible bit depths to 1, 2, 4, 8, and 16.  If your
3485data is of another bit depth, you can write an sBIT chunk into the
3486file so that decoders can recover the original data if desired.
3487
3488    /* Set the true bit depth of the image data */
3489    if (color_type & PNG_COLOR_MASK_COLOR)
3490    {
3491       sig_bit.red = true_bit_depth;
3492       sig_bit.green = true_bit_depth;
3493       sig_bit.blue = true_bit_depth;
3494    }
3495
3496    else
3497    {
3498       sig_bit.gray = true_bit_depth;
3499    }
3500
3501    if (color_type & PNG_COLOR_MASK_ALPHA)
3502    {
3503       sig_bit.alpha = true_bit_depth;
3504    }
3505
3506    png_set_sBIT(png_ptr, info_ptr, &sig_bit);
3507
3508If the data is stored in the row buffer in a bit depth other than
3509one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
3510this will scale the values to appear to be the correct bit depth as
3511is required by PNG.
3512
3513    png_set_shift(png_ptr, &sig_bit);
3514
3515PNG files store 16-bit pixels in network byte order (big-endian,
3516ie. most significant bits first).  This code would be used if they are
3517supplied the other way (little-endian, i.e. least significant bits
3518first, the way PCs store them):
3519
3520    if (bit_depth > 8)
3521       png_set_swap(png_ptr);
3522
3523If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
3524need to change the order the pixels are packed into bytes, you can use:
3525
3526    if (bit_depth < 8)
3527       png_set_packswap(png_ptr);
3528
3529PNG files store 3 color pixels in red, green, blue order.  This code
3530would be used if they are supplied as blue, green, red:
3531
3532    png_set_bgr(png_ptr);
3533
3534PNG files describe monochrome as black being zero and white being
3535one. This code would be used if the pixels are supplied with this reversed
3536(black being one and white being zero):
3537
3538    png_set_invert_mono(png_ptr);
3539
3540Finally, you can write your own transformation function if none of
3541the existing ones meets your needs.  This is done by setting a callback
3542with
3543
3544    png_set_write_user_transform_fn(png_ptr,
3545       write_transform_fn);
3546
3547You must supply the function
3548
3549    void write_transform_fn(png_structp png_ptr, png_row_infop
3550       row_info, png_bytep data)
3551
3552See pngtest.c for a working example.  Your function will be called
3553before any of the other transformations are processed.  If supported
3554libpng also supplies an information routine that may be called from
3555your callback:
3556
3557   png_get_current_row_number(png_ptr);
3558   png_get_current_pass_number(png_ptr);
3559
3560This returns the current row passed to the transform.  With interlaced
3561images the value returned is the row in the input sub-image image.  Use
3562PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
3563find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
3564
3565The discussion of interlace handling above contains more information on how to
3566use these values.
3567
3568You can also set up a pointer to a user structure for use by your
3569callback function.
3570
3571    png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
3572
3573The user_channels and user_depth parameters of this function are ignored
3574when writing; you can set them to zero as shown.
3575
3576You can retrieve the pointer via the function png_get_user_transform_ptr().
3577For example:
3578
3579    voidp write_user_transform_ptr =
3580       png_get_user_transform_ptr(png_ptr);
3581
3582It is possible to have libpng flush any pending output, either manually,
3583or automatically after a certain number of lines have been written.  To
3584flush the output stream a single time call:
3585
3586    png_write_flush(png_ptr);
3587
3588and to have libpng flush the output stream periodically after a certain
3589number of scanlines have been written, call:
3590
3591    png_set_flush(png_ptr, nrows);
3592
3593Note that the distance between rows is from the last time png_write_flush()
3594was called, or the first row of the image if it has never been called.
3595So if you write 50 lines, and then png_set_flush 25, it will flush the
3596output on the next scanline, and every 25 lines thereafter, unless
3597png_write_flush() is called before 25 more lines have been written.
3598If nrows is too small (less than about 10 lines for a 640 pixel wide
3599RGB image) the image compression may decrease noticeably (although this
3600may be acceptable for real-time applications).  Infrequent flushing will
3601only degrade the compression performance by a few percent over images
3602that do not use flushing.
3603
3604Writing the image data
3605
3606That's it for the transformations.  Now you can write the image data.
3607The simplest way to do this is in one function call.  If you have the
3608whole image in memory, you can just call png_write_image() and libpng
3609will write the image.  You will need to pass in an array of pointers to
3610each row.  This function automatically handles interlacing, so you don't
3611need to call png_set_interlace_handling() or call this function multiple
3612times, or any of that other stuff necessary with png_write_rows().
3613
3614    png_write_image(png_ptr, row_pointers);
3615
3616where row_pointers is:
3617
3618    png_byte *row_pointers[height];
3619
3620You can point to void or char or whatever you use for pixels.
3621
3622If you don't want to write the whole image at once, you can
3623use png_write_rows() instead.  If the file is not interlaced,
3624this is simple:
3625
3626    png_write_rows(png_ptr, row_pointers,
3627       number_of_rows);
3628
3629row_pointers is the same as in the png_write_image() call.
3630
3631If you are just writing one row at a time, you can do this with
3632a single row_pointer instead of an array of row_pointers:
3633
3634    png_bytep row_pointer = row;
3635
3636    png_write_row(png_ptr, row_pointer);
3637
3638When the file is interlaced, things can get a good deal more complicated.
3639The only currently (as of the PNG Specification version 1.2, dated July
36401999) defined interlacing scheme for PNG files is the "Adam7" interlace
3641scheme, that breaks down an image into seven smaller images of varying
3642size.  libpng will build these images for you, or you can do them
3643yourself.  If you want to build them yourself, see the PNG specification
3644for details of which pixels to write when.
3645
3646If you don't want libpng to handle the interlacing details, just
3647use png_set_interlace_handling() and call png_write_rows() the
3648correct number of times to write all the sub-images
3649(png_set_interlace_handling() returns the number of sub-images.)
3650
3651If you want libpng to build the sub-images, call this before you start
3652writing any rows:
3653
3654    number_of_passes = png_set_interlace_handling(png_ptr);
3655
3656This will return the number of passes needed.  Currently, this is seven,
3657but may change if another interlace type is added.
3658
3659Then write the complete image number_of_passes times.
3660
3661    png_write_rows(png_ptr, row_pointers, number_of_rows);
3662
3663Think carefully before you write an interlaced image.  Typically code that
3664reads such images reads all the image data into memory, uncompressed, before
3665doing any processing.  Only code that can display an image on the fly can
3666take advantage of the interlacing and even then the image has to be exactly
3667the correct size for the output device, because scaling an image requires
3668adjacent pixels and these are not available until all the passes have been
3669read.
3670
3671If you do write an interlaced image you will hardly ever need to handle
3672the interlacing yourself.  Call png_set_interlace_handling() and use the
3673approach described above.
3674
3675The only time it is conceivable that you will really need to write an
3676interlaced image pass-by-pass is when you have read one pass by pass and
3677made some pixel-by-pixel transformation to it, as described in the read
3678code above.  In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros
3679to determine the size of each sub-image in turn and simply write the rows
3680you obtained from the read code.
3681
3682Finishing a sequential write
3683
3684After you are finished writing the image, you should finish writing
3685the file.  If you are interested in writing comments or time, you should
3686pass an appropriately filled png_info pointer.  If you are not interested,
3687you can pass NULL.
3688
3689    png_write_end(png_ptr, info_ptr);
3690
3691When you are done, you can free all memory used by libpng like this:
3692
3693    png_destroy_write_struct(&png_ptr, &info_ptr);
3694
3695It is also possible to individually free the info_ptr members that
3696point to libpng-allocated storage with the following function:
3697
3698    png_free_data(png_ptr, info_ptr, mask, seq)
3699
3700    mask  - identifies data to be freed, a mask
3701            containing the bitwise OR of one or
3702            more of
3703              PNG_FREE_PLTE, PNG_FREE_TRNS,
3704              PNG_FREE_HIST, PNG_FREE_ICCP,
3705              PNG_FREE_PCAL, PNG_FREE_ROWS,
3706              PNG_FREE_SCAL, PNG_FREE_SPLT,
3707              PNG_FREE_TEXT, PNG_FREE_UNKN,
3708            or simply PNG_FREE_ALL
3709
3710    seq   - sequence number of item to be freed
3711            (-1 for all items)
3712
3713This function may be safely called when the relevant storage has
3714already been freed, or has not yet been allocated, or was allocated
3715by the user  and not by libpng,  and will in those cases do nothing.
3716The "seq" parameter is ignored if only one item of the selected data
3717type, such as PLTE, is allowed.  If "seq" is not -1, and multiple items
3718are allowed for the data type identified in the mask, such as text or
3719sPLT, only the n'th item in the structure is freed, where n is "seq".
3720
3721If you allocated data such as a palette that you passed in to libpng
3722with png_set_*, you must not free it until just before the call to
3723png_destroy_write_struct().
3724
3725The default behavior is only to free data that was allocated internally
3726by libpng.  This can be changed, so that libpng will not free the data,
3727or so that it will free data that was allocated by the user with png_malloc()
3728or png_calloc() and passed in via a png_set_*() function, with
3729
3730    png_data_freer(png_ptr, info_ptr, freer, mask)
3731
3732    freer  - one of
3733               PNG_DESTROY_WILL_FREE_DATA
3734               PNG_SET_WILL_FREE_DATA
3735               PNG_USER_WILL_FREE_DATA
3736
3737    mask   - which data elements are affected
3738             same choices as in png_free_data()
3739
3740For example, to transfer responsibility for some data from a read structure
3741to a write structure, you could use
3742
3743    png_data_freer(read_ptr, read_info_ptr,
3744       PNG_USER_WILL_FREE_DATA,
3745       PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3746
3747    png_data_freer(write_ptr, write_info_ptr,
3748       PNG_DESTROY_WILL_FREE_DATA,
3749       PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3750
3751thereby briefly reassigning responsibility for freeing to the user but
3752immediately afterwards reassigning it once more to the write_destroy
3753function.  Having done this, it would then be safe to destroy the read
3754structure and continue to use the PLTE, tRNS, and hIST data in the write
3755structure.
3756
3757This function only affects data that has already been allocated.
3758You can call this function before calling after the png_set_*() functions
3759to control whether the user or png_destroy_*() is supposed to free the data.
3760When the user assumes responsibility for libpng-allocated data, the
3761application must use
3762png_free() to free it, and when the user transfers responsibility to libpng
3763for data that the user has allocated, the user must have used png_malloc()
3764or png_calloc() to allocate it.
3765
3766If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
3767separately, do not transfer responsibility for freeing text_ptr to libpng,
3768because when libpng fills a png_text structure it combines these members with
3769the key member, and png_free_data() will free only text_ptr.key.  Similarly,
3770if you transfer responsibility for free'ing text_ptr from libpng to your
3771application, your application must not separately free those members.
3772For a more compact example of writing a PNG image, see the file example.c.
3773
3774V. Simplified API
3775
3776The simplified API, which became available in libpng-1.6.0, hides the details
3777of both libpng and the PNG file format itself.
3778It allows PNG files to be read into a very limited number of
3779in-memory bitmap formats or to be written from the same formats.  If these
3780formats do not accommodate your needs then you can, and should, use the more
3781sophisticated APIs above - these support a wide variety of in-memory formats
3782and a wide variety of sophisticated transformations to those formats as well
3783as a wide variety of APIs to manipulate ancillary information.
3784
3785To read a PNG file using the simplified API:
3786
3787  1) Declare a 'png_image' structure (see below) on the stack, set the
3788     version field to PNG_IMAGE_VERSION and the 'opaque' pointer to NULL
3789     (this is REQUIRED, your program may crash if you don't do it.)
3790
3791  2) Call the appropriate png_image_begin_read... function.
3792
3793  3) Set the png_image 'format' member to the required sample format.
3794
3795  4) Allocate a buffer for the image and, if required, the color-map.
3796
3797  5) Call png_image_finish_read to read the image and, if required, the
3798     color-map into your buffers.
3799
3800There are no restrictions on the format of the PNG input itself; all valid
3801color types, bit depths, and interlace methods are acceptable, and the
3802input image is transformed as necessary to the requested in-memory format
3803during the png_image_finish_read() step.  The only caveat is that if you
3804request a color-mapped image from a PNG that is full-color or makes
3805complex use of an alpha channel the transformation is extremely lossy and the
3806result may look terrible.
3807
3808To write a PNG file using the simplified API:
3809
3810  1) Declare a 'png_image' structure on the stack and memset()
3811     it to all zero.
3812
3813  2) Initialize the members of the structure that describe the
3814     image, setting the 'format' member to the format of the
3815     image samples.
3816
3817  3) Call the appropriate png_image_write... function with a
3818     pointer to the image and, if necessary, the color-map to write
3819     the PNG data.
3820
3821png_image is a structure that describes the in-memory format of an image
3822when it is being read or defines the in-memory format of an image that you
3823need to write.  The "png_image" structure contains the following members:
3824
3825   png_controlp opaque  Initialize to NULL, free with png_image_free
3826   png_uint_32  version Set to PNG_IMAGE_VERSION
3827   png_uint_32  width   Image width in pixels (columns)
3828   png_uint_32  height  Image height in pixels (rows)
3829   png_uint_32  format  Image format as defined below
3830   png_uint_32  flags   A bit mask containing informational flags
3831   png_uint_32  colormap_entries; Number of entries in the color-map
3832   png_uint_32  warning_or_error;
3833   char         message[64];
3834
3835In the event of an error or warning the "warning_or_error"
3836field will be set to a non-zero value and the 'message' field will contain
3837a '\0' terminated string with the libpng error or warning message.  If both
3838warnings and an error were encountered, only the error is recorded.  If there
3839are multiple warnings, only the first one is recorded.
3840
3841The upper 30 bits of the "warning_or_error" value are reserved; the low two
3842bits contain a two bit code such that a value more than 1 indicates a failure
3843in the API just called:
3844
3845   0 - no warning or error
3846   1 - warning
3847   2 - error
3848   3 - error preceded by warning
3849
3850The pixels (samples) of the image have one to four channels whose components
3851have original values in the range 0 to 1.0:
3852
3853  1: A single gray or luminance channel (G).
3854  2: A gray/luminance channel and an alpha channel (GA).
3855  3: Three red, green, blue color channels (RGB).
3856  4: Three color channels and an alpha channel (RGBA).
3857
3858The channels are encoded in one of two ways:
3859
3860  a) As a small integer, value 0..255, contained in a single byte.  For the
3861alpha channel the original value is simply value/255.  For the color or
3862luminance channels the value is encoded according to the sRGB specification
3863and matches the 8-bit format expected by typical display devices.
3864
3865The color/gray channels are not scaled (pre-multiplied) by the alpha
3866channel and are suitable for passing to color management software.
3867
3868  b) As a value in the range 0..65535, contained in a 2-byte integer, in
3869the native byte order of the platform on which the application is running.
3870All channels can be converted to the original value by dividing by 65535; all
3871channels are linear.  Color channels use the RGB encoding (RGB end-points) of
3872the sRGB specification.  This encoding is identified by the
3873PNG_FORMAT_FLAG_LINEAR flag below.
3874
3875When the simplified API needs to convert between sRGB and linear colorspaces,
3876the actual sRGB transfer curve defined in the sRGB specification (see the
3877article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
3878approximation used elsewhere in libpng.
3879
3880When an alpha channel is present it is expected to denote pixel coverage
3881of the color or luminance channels and is returned as an associated alpha
3882channel: the color/gray channels are scaled (pre-multiplied) by the alpha
3883value.
3884
3885The samples are either contained directly in the image data, between 1 and 8
3886bytes per pixel according to the encoding, or are held in a color-map indexed
3887by bytes in the image data.  In the case of a color-map the color-map entries
3888are individual samples, encoded as above, and the image data has one byte per
3889pixel to select the relevant sample from the color-map.
3890
3891PNG_FORMAT_*
3892
3893The #defines to be used in png_image::format.  Each #define identifies a
3894particular layout of channel data and, if present, alpha values.  There are
3895separate defines for each of the two component encodings.
3896
3897A format is built up using single bit flag values.  All combinations are
3898valid.  Formats can be built up from the flag values or you can use one of
3899the predefined values below.  When testing formats always use the FORMAT_FLAG
3900macros to test for individual features - future versions of the library may
3901add new flags.
3902
3903When reading or writing color-mapped images the format should be set to the
3904format of the entries in the color-map then png_image_{read,write}_colormap
3905called to read or write the color-map and set the format correctly for the
3906image data.  Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly!
3907
3908NOTE: libpng can be built with particular features disabled. If you see
3909compiler errors because the definition of one of the following flags has been
3910compiled out it is because libpng does not have the required support.  It is
3911possible, however, for the libpng configuration to enable the format on just
3912read or just write; in that case you may see an error at run time.
3913You can guard against this by checking for the definition of the
3914appropriate "_SUPPORTED" macro, one of:
3915
3916   PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED
3917
3918   PNG_FORMAT_FLAG_ALPHA    format with an alpha channel
3919   PNG_FORMAT_FLAG_COLOR    color format: otherwise grayscale
3920   PNG_FORMAT_FLAG_LINEAR   2-byte channels else 1-byte
3921   PNG_FORMAT_FLAG_COLORMAP image data is color-mapped
3922   PNG_FORMAT_FLAG_BGR      BGR colors, else order is RGB
3923   PNG_FORMAT_FLAG_AFIRST   alpha channel comes first
3924
3925Supported formats are as follows.  Future versions of libpng may support more
3926formats; for compatibility with older versions simply check if the format
3927macro is defined using #ifdef.  These defines describe the in-memory layout
3928of the components of the pixels of the image.
3929
3930First the single byte (sRGB) formats:
3931
3932   PNG_FORMAT_GRAY
3933   PNG_FORMAT_GA
3934   PNG_FORMAT_AG
3935   PNG_FORMAT_RGB
3936   PNG_FORMAT_BGR
3937   PNG_FORMAT_RGBA
3938   PNG_FORMAT_ARGB
3939   PNG_FORMAT_BGRA
3940   PNG_FORMAT_ABGR
3941
3942Then the linear 2-byte formats.  When naming these "Y" is used to
3943indicate a luminance (gray) channel.  The component order within the pixel
3944is always the same - there is no provision for swapping the order of the
3945components in the linear format.  The components are 16-bit integers in
3946the native byte order for your platform, and there is no provision for
3947swapping the bytes to a different endian condition.
3948
3949   PNG_FORMAT_LINEAR_Y
3950   PNG_FORMAT_LINEAR_Y_ALPHA
3951   PNG_FORMAT_LINEAR_RGB
3952   PNG_FORMAT_LINEAR_RGB_ALPHA
3953
3954With color-mapped formats the image data is one byte for each pixel. The byte
3955is an index into the color-map which is formatted as above.  To obtain a
3956color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP
3957to one of the above definitions, or you can use one of the definitions below.
3958
3959   PNG_FORMAT_RGB_COLORMAP
3960   PNG_FORMAT_BGR_COLORMAP
3961   PNG_FORMAT_RGBA_COLORMAP
3962   PNG_FORMAT_ARGB_COLORMAP
3963   PNG_FORMAT_BGRA_COLORMAP
3964   PNG_FORMAT_ABGR_COLORMAP
3965
3966PNG_IMAGE macros
3967
3968These are convenience macros to derive information from a png_image
3969structure.  The PNG_IMAGE_SAMPLE_ macros return values appropriate to the
3970actual image sample values - either the entries in the color-map or the
3971pixels in the image.  The PNG_IMAGE_PIXEL_ macros return corresponding values
3972for the pixels and will always return 1 for color-mapped formats.  The
3973remaining macros return information about the rows in the image and the
3974complete image.
3975
3976NOTE: All the macros that take a png_image::format parameter are compile time
3977constants if the format parameter is, itself, a constant.  Therefore these
3978macros can be used in array declarations and case labels where required.
3979Similarly the macros are also pre-processor constants (sizeof is not used) so
3980they can be used in #if tests.
3981
3982  PNG_IMAGE_SAMPLE_CHANNELS(fmt)
3983    Returns the total number of channels in a given format: 1..4
3984
3985  PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt)
3986    Returns the size in bytes of a single component of a pixel or color-map
3987    entry (as appropriate) in the image: 1 or 2.
3988
3989  PNG_IMAGE_SAMPLE_SIZE(fmt)
3990    This is the size of the sample data for one sample.  If the image is
3991    color-mapped it is the size of one color-map entry (and image pixels are
3992    one byte in size), otherwise it is the size of one image pixel.
3993
3994  PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)
3995    The maximum size of the color-map required by the format expressed in a
3996    count of components.  This can be used to compile-time allocate a
3997    color-map:
3998
3999    png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)];
4000
4001    png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)];
4002
4003    Alternatively use the PNG_IMAGE_COLORMAP_SIZE macro below to use the
4004    information from one of the png_image_begin_read_ APIs and dynamically
4005    allocate the required memory.
4006
4007  PNG_IMAGE_COLORMAP_SIZE(fmt)
4008   The size of the color-map required by the format; this is the size of the
4009   color-map buffer passed to the png_image_{read,write}_colormap APIs. It is
4010   a fixed number determined by the format so can easily be allocated on the
4011   stack if necessary.
4012
4013Corresponding information about the pixels
4014
4015  PNG_IMAGE_PIXEL_CHANNELS(fmt)
4016   The number of separate channels (components) in a pixel; 1 for a
4017   color-mapped image.
4018
4019  PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\
4020   The size, in bytes, of each component in a pixel; 1 for a color-mapped
4021   image.
4022
4023  PNG_IMAGE_PIXEL_SIZE(fmt)
4024   The size, in bytes, of a complete pixel; 1 for a color-mapped image.
4025
4026Information about the whole row, or whole image
4027
4028  PNG_IMAGE_ROW_STRIDE(image)
4029   Returns the total number of components in a single row of the image; this
4030   is the minimum 'row stride', the minimum count of components between each
4031   row.  For a color-mapped image this is the minimum number of bytes in a
4032   row.
4033
4034   If you need the stride measured in bytes, row_stride_bytes is
4035   PNG_IMAGE_ROW_STRIDE(image) * PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)
4036   plus any padding bytes that your application might need, for example
4037   to start the next row on a 4-byte boundary.
4038
4039  PNG_IMAGE_BUFFER_SIZE(image, row_stride)
4040   Return the size, in bytes, of an image buffer given a png_image and a row
4041   stride - the number of components to leave space for in each row.
4042
4043  PNG_IMAGE_SIZE(image)
4044   Return the size, in bytes, of the image in memory given just a png_image;
4045   the row stride is the minimum stride required for the image.
4046
4047  PNG_IMAGE_COLORMAP_SIZE(image)
4048   Return the size, in bytes, of the color-map of this image.  If the image
4049   format is not a color-map format this will return a size sufficient for
4050   256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if
4051   you don't want to allocate a color-map in this case.
4052
4053PNG_IMAGE_FLAG_*
4054
4055Flags containing additional information about the image are held in
4056the 'flags' field of png_image.
4057
4058  PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01
4059    This indicates that the RGB values of the in-memory bitmap do not
4060    correspond to the red, green and blue end-points defined by sRGB.
4061
4062  PNG_IMAGE_FLAG_FAST == 0x02
4063   On write emphasise speed over compression; the resultant PNG file will be
4064   larger but will be produced significantly faster, particular for large
4065   images.  Do not use this option for images which will be distributed, only
4066   used it when producing intermediate files that will be read back in
4067   repeatedly.  For a typical 24-bit image the option will double the read
4068   speed at the cost of increasing the image size by 25%, however for many
4069   more compressible images the PNG file can be 10 times larger with only a
4070   slight speed gain.
4071
4072  PNG_IMAGE_FLAG_16BIT_sRGB == 0x04
4073    On read if the image is a 16-bit per component image and there is no gAMA
4074    or sRGB chunk assume that the components are sRGB encoded.  Notice that
4075    images output by the simplified API always have gamma information; setting
4076    this flag only affects the interpretation of 16-bit images from an
4077    external source.  It is recommended that the application expose this flag
4078    to the user; the user can normally easily recognize the difference between
4079    linear and sRGB encoding.  This flag has no effect on write - the data
4080    passed to the write APIs must have the correct encoding (as defined
4081    above.)
4082
4083    If the flag is not set (the default) input 16-bit per component data is
4084    assumed to be linear.
4085
4086    NOTE: the flag can only be set after the png_image_begin_read_ call,
4087    because that call initializes the 'flags' field.
4088
4089READ APIs
4090
4091   The png_image passed to the read APIs must have been initialized by setting
4092   the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.)
4093
4094   int png_image_begin_read_from_file( png_imagep image,
4095     const char *file_name)
4096
4097     The named file is opened for read and the image header
4098     is filled in from the PNG header in the file.
4099
4100   int png_image_begin_read_from_stdio (png_imagep image,
4101     FILE* file)
4102
4103      The PNG header is read from the stdio FILE object.
4104
4105   int png_image_begin_read_from_memory(png_imagep image,
4106      png_const_voidp memory, size_t size)
4107
4108      The PNG header is read from the given memory buffer.
4109
4110   int png_image_finish_read(png_imagep image,
4111      png_colorp background, void *buffer,
4112      png_int_32 row_stride, void *colormap));
4113
4114      Finish reading the image into the supplied buffer and
4115      clean up the png_image structure.
4116
4117      row_stride is the step, in png_byte or png_uint_16 units
4118      as appropriate, between adjacent rows.  A positive stride
4119      indicates that the top-most row is first in the buffer -
4120      the normal top-down arrangement.  A negative stride
4121      indicates that the bottom-most row is first in the buffer.
4122
4123      background need only be supplied if an alpha channel must
4124      be removed from a png_byte format and the removal is to be
4125      done by compositing on a solid color; otherwise it may be
4126      NULL and any composition will be done directly onto the
4127      buffer.  The value is an sRGB color to use for the
4128      background, for grayscale output the green channel is used.
4129
4130      For linear output removing the alpha channel is always done
4131      by compositing on black.
4132
4133   void png_image_free(png_imagep image)
4134
4135      Free any data allocated by libpng in image->opaque,
4136      setting the pointer to NULL.  May be called at any time
4137      after the structure is initialized.
4138
4139When the simplified API needs to convert between sRGB and linear colorspaces,
4140the actual sRGB transfer curve defined in the sRGB specification (see the
4141article at https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2
4142approximation used elsewhere in libpng.
4143
4144WRITE APIS
4145
4146For write you must initialize a png_image structure to describe the image to
4147be written:
4148
4149   version: must be set to PNG_IMAGE_VERSION
4150   opaque: must be initialized to NULL
4151   width: image width in pixels
4152   height: image height in rows
4153   format: the format of the data you wish to write
4154   flags: set to 0 unless one of the defined flags applies; set
4155      PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images
4156      where the RGB values do not correspond to the colors in sRGB.
4157   colormap_entries: set to the number of entries in the color-map (0 to 256)
4158
4159   int png_image_write_to_file, (png_imagep image,
4160      const char *file, int convert_to_8bit, const void *buffer,
4161      png_int_32 row_stride, const void *colormap));
4162
4163      Write the image to the named file.
4164
4165   int png_image_write_to_memory (png_imagep image, void *memory,
4166      png_alloc_size_t * PNG_RESTRICT memory_bytes,
4167      int convert_to_8_bit, const void *buffer, ptrdiff_t row_stride,
4168      const void *colormap));
4169
4170      Write the image to memory.
4171
4172   int png_image_write_to_stdio(png_imagep image, FILE *file,
4173      int convert_to_8_bit, const void *buffer,
4174      png_int_32 row_stride, const void *colormap)
4175
4176      Write the image to the given (FILE*).
4177
4178With all write APIs if image is in one of the linear formats with
4179(png_uint_16) data then setting convert_to_8_bit will cause the output to be
4180a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise
4181a 16-bit linear encoded PNG file is written.
4182
4183With all APIs row_stride is handled as in the read APIs - it is the spacing
4184from one row to the next in component sized units (float) and if negative
4185indicates a bottom-up row layout in the buffer.  If you pass zero, libpng will
4186calculate the row_stride for you from the width and number of channels.
4187
4188Note that the write API does not support interlacing, sub-8-bit pixels,
4189indexed (paletted) images, or most ancillary chunks.
4190
4191VI. Modifying/Customizing libpng
4192
4193There are two issues here.  The first is changing how libpng does
4194standard things like memory allocation, input/output, and error handling.
4195The second deals with more complicated things like adding new chunks,
4196adding new transformations, and generally changing how libpng works.
4197Both of those are compile-time issues; that is, they are generally
4198determined at the time the code is written, and there is rarely a need
4199to provide the user with a means of changing them.
4200
4201Memory allocation, input/output, and error handling
4202
4203All of the memory allocation, input/output, and error handling in libpng
4204goes through callbacks that are user-settable.  The default routines are
4205in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively.  To change
4206these functions, call the appropriate png_set_*_fn() function.
4207
4208Memory allocation is done through the functions png_malloc(), png_calloc(),
4209and png_free().  The png_malloc() and png_free() functions currently just
4210call the standard C functions and png_calloc() calls png_malloc() and then
4211clears the newly allocated memory to zero; note that png_calloc(png_ptr, size)
4212is not the same as the calloc(number, size) function provided by stdlib.h.
4213There is limited support for certain systems with segmented memory
4214architectures and the types of pointers declared by png.h match this; you
4215will have to use appropriate pointers in your application.  If you prefer
4216to use a different method of allocating and freeing data, you can use
4217png_create_read_struct_2() or png_create_write_struct_2() to register your
4218own functions as described above.  These functions also provide a void
4219pointer that can be retrieved via
4220
4221    mem_ptr=png_get_mem_ptr(png_ptr);
4222
4223Your replacement memory functions must have prototypes as follows:
4224
4225    png_voidp malloc_fn(png_structp png_ptr,
4226       png_alloc_size_t size);
4227
4228    void free_fn(png_structp png_ptr, png_voidp ptr);
4229
4230Your malloc_fn() must return NULL in case of failure.  The png_malloc()
4231function will normally call png_error() if it receives a NULL from the
4232system memory allocator or from your replacement malloc_fn().
4233
4234Your free_fn() will never be called with a NULL ptr, since libpng's
4235png_free() checks for NULL before calling free_fn().
4236
4237Input/Output in libpng is done through png_read() and png_write(),
4238which currently just call fread() and fwrite().  The FILE * is stored in
4239png_struct and is initialized via png_init_io().  If you wish to change
4240the method of I/O, the library supplies callbacks that you can set
4241through the function png_set_read_fn() and png_set_write_fn() at run
4242time, instead of calling the png_init_io() function.  These functions
4243also provide a void pointer that can be retrieved via the function
4244png_get_io_ptr().  For example:
4245
4246    png_set_read_fn(png_structp read_ptr,
4247        voidp read_io_ptr, png_rw_ptr read_data_fn)
4248
4249    png_set_write_fn(png_structp write_ptr,
4250        voidp write_io_ptr, png_rw_ptr write_data_fn,
4251        png_flush_ptr output_flush_fn);
4252
4253    voidp read_io_ptr = png_get_io_ptr(read_ptr);
4254    voidp write_io_ptr = png_get_io_ptr(write_ptr);
4255
4256The replacement I/O functions must have prototypes as follows:
4257
4258    void user_read_data(png_structp png_ptr,
4259        png_bytep data, size_t length);
4260
4261    void user_write_data(png_structp png_ptr,
4262        png_bytep data, size_t length);
4263
4264    void user_flush_data(png_structp png_ptr);
4265
4266The user_read_data() function is responsible for detecting and
4267handling end-of-data errors.
4268
4269Supplying NULL for the read, write, or flush functions sets them back
4270to using the default C stream functions, which expect the io_ptr to
4271point to a standard *FILE structure.  It is probably a mistake
4272to use NULL for one of write_data_fn and output_flush_fn but not both
4273of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
4274It is an error to read from a write stream, and vice versa.
4275
4276Error handling in libpng is done through png_error() and png_warning().
4277Errors handled through png_error() are fatal, meaning that png_error()
4278should never return to its caller.  Currently, this is handled via
4279setjmp() and longjmp() (unless you have compiled libpng with
4280PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
4281but you could change this to do things like exit() if you should wish,
4282as long as your function does not return.
4283
4284On non-fatal errors, png_warning() is called
4285to print a warning message, and then control returns to the calling code.
4286By default png_error() and png_warning() print a message on stderr via
4287fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
4288(because you don't want the messages) or PNG_NO_STDIO defined (because
4289fprintf() isn't available).  If you wish to change the behavior of the error
4290functions, you will need to set up your own message callbacks.  These
4291functions are normally supplied at the time that the png_struct is created.
4292It is also possible to redirect errors and warnings to your own replacement
4293functions after png_create_*_struct() has been called by calling:
4294
4295    png_set_error_fn(png_structp png_ptr,
4296        png_voidp error_ptr, png_error_ptr error_fn,
4297        png_error_ptr warning_fn);
4298
4299If NULL is supplied for either error_fn or warning_fn, then the libpng
4300default function will be used, calling fprintf() and/or longjmp() if a
4301problem is encountered.  The replacement error functions should have
4302parameters as follows:
4303
4304    void user_error_fn(png_structp png_ptr,
4305        png_const_charp error_msg);
4306
4307    void user_warning_fn(png_structp png_ptr,
4308        png_const_charp warning_msg);
4309
4310Then, within your user_error_fn or user_warning_fn, you can retrieve
4311the error_ptr if you need it, by calling
4312
4313    png_voidp error_ptr = png_get_error_ptr(png_ptr);
4314
4315The motivation behind using setjmp() and longjmp() is the C++ throw and
4316catch exception handling methods.  This makes the code much easier to write,
4317as there is no need to check every return code of every function call.
4318However, there are some uncertainties about the status of local variables
4319after a longjmp, so the user may want to be careful about doing anything
4320after setjmp returns non-zero besides returning itself.  Consult your
4321compiler documentation for more details.  For an alternative approach, you
4322may wish to use the "cexcept" facility (see https://cexcept.sourceforge.io/),
4323which is illustrated in pngvalid.c and in contrib/visupng.
4324
4325Beginning in libpng-1.4.0, the png_set_benign_errors() API became available.
4326You can use this to handle certain errors (normally handled as errors)
4327as warnings.
4328
4329    png_set_benign_errors (png_ptr, int allowed);
4330
4331    allowed: 0: treat png_benign_error() as an error.
4332             1: treat png_benign_error() as a warning.
4333
4334As of libpng-1.6.0, the default condition is to treat benign errors as
4335warnings while reading and as errors while writing.
4336
4337Custom chunks
4338
4339If you need to read or write custom chunks, you may need to get deeper
4340into the libpng code.  The library now has mechanisms for storing
4341and writing chunks of unknown type; you can even declare callbacks
4342for custom chunks.  However, this may not be good enough if the
4343library code itself needs to know about interactions between your
4344chunk and existing `intrinsic' chunks.
4345
4346If you need to write a new intrinsic chunk, first read the PNG
4347specification. Acquire a first level of understanding of how it works.
4348Pay particular attention to the sections that describe chunk names,
4349and look at how other chunks were designed, so you can do things
4350similarly.  Second, check out the sections of libpng that read and
4351write chunks.  Try to find a chunk that is similar to yours and use
4352it as a template.  More details can be found in the comments inside
4353the code.  It is best to handle private or unknown chunks in a generic method,
4354via callback functions, instead of by modifying libpng functions. This
4355is illustrated in pngtest.c, which uses a callback function to handle a
4356private "vpAg" chunk and the new "sTER" chunk, which are both unknown to
4357libpng.
4358
4359If you wish to write your own transformation for the data, look through
4360the part of the code that does the transformations, and check out some of
4361the simpler ones to get an idea of how they work.  Try to find a similar
4362transformation to the one you want to add and copy off of it.  More details
4363can be found in the comments inside the code itself.
4364
4365Configuring for gui/windowing platforms:
4366
4367You will need to write new error and warning functions that use the GUI
4368interface, as described previously, and set them to be the error and
4369warning functions at the time that png_create_*_struct() is called,
4370in order to have them available during the structure initialization.
4371They can be changed later via png_set_error_fn().  On some compilers,
4372you may also have to change the memory allocators (png_malloc, etc.).
4373
4374Configuring zlib:
4375
4376There are special functions to configure the compression.  Perhaps the
4377most useful one changes the compression level, which currently uses
4378input compression values in the range 0 - 9.  The library normally
4379uses the default compression level (Z_DEFAULT_COMPRESSION = 6).  Tests
4380have shown that for a large majority of images, compression values in
4381the range 3-6 compress nearly as well as higher levels, and do so much
4382faster.  For online applications it may be desirable to have maximum speed
4383(Z_BEST_SPEED = 1).  With versions of zlib after v0.99, you can also
4384specify no compression (Z_NO_COMPRESSION = 0), but this would create
4385files larger than just storing the raw bitmap.  You can specify the
4386compression level by calling:
4387
4388    #include zlib.h
4389    png_set_compression_level(png_ptr, level);
4390
4391Another useful one is to reduce the memory level used by the library.
4392The memory level defaults to 8, but it can be lowered if you are
4393short on memory (running DOS, for example, where you only have 640K).
4394Note that the memory level does have an effect on compression; among
4395other things, lower levels will result in sections of incompressible
4396data being emitted in smaller stored blocks, with a correspondingly
4397larger relative overhead of up to 15% in the worst case.
4398
4399    #include zlib.h
4400    png_set_compression_mem_level(png_ptr, level);
4401
4402The other functions are for configuring zlib.  They are not recommended
4403for normal use and may result in writing an invalid PNG file.  See
4404zlib.h for more information on what these mean.
4405
4406    #include zlib.h
4407    png_set_compression_strategy(png_ptr,
4408        strategy);
4409
4410    png_set_compression_window_bits(png_ptr,
4411        window_bits);
4412
4413    png_set_compression_method(png_ptr, method);
4414
4415This controls the size of the IDAT chunks (default 8192):
4416
4417    png_set_compression_buffer_size(png_ptr, size);
4418
4419As of libpng version 1.5.4, additional APIs became
4420available to set these separately for non-IDAT
4421compressed chunks such as zTXt, iTXt, and iCCP:
4422
4423    #include zlib.h
4424    #if PNG_LIBPNG_VER >= 10504
4425    png_set_text_compression_level(png_ptr, level);
4426
4427    png_set_text_compression_mem_level(png_ptr, level);
4428
4429    png_set_text_compression_strategy(png_ptr,
4430        strategy);
4431
4432    png_set_text_compression_window_bits(png_ptr,
4433        window_bits);
4434
4435    png_set_text_compression_method(png_ptr, method);
4436    #endif
4437
4438Controlling row filtering
4439
4440If you want to control whether libpng uses filtering or not, which
4441filters are used, and how it goes about picking row filters, you
4442can call one of these functions.  The selection and configuration
4443of row filters can have a significant impact on the size and
4444encoding speed and a somewhat lesser impact on the decoding speed
4445of an image.  Filtering is enabled by default for RGB and grayscale
4446images (with and without alpha), but not for paletted images nor
4447for any images with bit depths less than 8 bits/pixel.
4448
4449The 'method' parameter sets the main filtering method, which is
4450currently only '0' in the PNG 1.2 specification.  The 'filters'
4451parameter sets which filter(s), if any, should be used for each
4452scanline.  Possible values are PNG_ALL_FILTERS, PNG_NO_FILTERS,
4453or PNG_FAST_FILTERS to turn filtering on and off, or to turn on
4454just the fast-decoding subset of filters, respectively.
4455
4456Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
4457PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
4458ORed together with '|' to specify one or more filters to use.
4459These filters are described in more detail in the PNG specification.
4460If you intend to change the filter type during the course of writing
4461the image, you should start with flags set for all of the filters
4462you intend to use so that libpng can initialize its internal
4463structures appropriately for all of the filter types.  (Note that this
4464means the first row must always be adaptively filtered, because libpng
4465currently does not allocate the filter buffers until png_write_row()
4466is called for the first time.)
4467
4468    filters = PNG_NO_FILTERS;
4469    filters = PNG_ALL_FILTERS;
4470    filters = PNG_FAST_FILTERS;
4471
4472    or
4473
4474    filters = PNG_FILTER_NONE | PNG_FILTER_SUB |
4475              PNG_FILTER_UP | PNG_FILTER_AVG |
4476              PNG_FILTER_PAETH;
4477
4478    png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
4479       filters);
4480
4481              The second parameter can also be
4482              PNG_INTRAPIXEL_DIFFERENCING if you are
4483              writing a PNG to be embedded in a MNG
4484              datastream.  This parameter must be the
4485              same as the value of filter_method used
4486              in png_set_IHDR().
4487
4488Requesting debug printout
4489
4490The macro definition PNG_DEBUG can be used to request debugging
4491printout.  Set it to an integer value in the range 0 to 3.  Higher
4492numbers result in increasing amounts of debugging information.  The
4493information is printed to the "stderr" file, unless another file
4494name is specified in the PNG_DEBUG_FILE macro definition.
4495
4496When PNG_DEBUG > 0, the following functions (macros) become available:
4497
4498   png_debug(level, message)
4499   png_debug1(level, message, p1)
4500   png_debug2(level, message, p1, p2)
4501
4502in which "level" is compared to PNG_DEBUG to decide whether to print
4503the message, "message" is the formatted string to be printed,
4504and p1 and p2 are parameters that are to be embedded in the string
4505according to printf-style formatting directives.  For example,
4506
4507   png_debug1(2, "foo=%d", foo);
4508
4509is expanded to
4510
4511   if (PNG_DEBUG > 2)
4512      fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
4513
4514When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
4515can still use PNG_DEBUG to control your own debugging:
4516
4517   #ifdef PNG_DEBUG
4518       fprintf(stderr, ...
4519   #endif
4520
4521When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
4522having level = 0 will be printed.  There aren't any such statements in
4523this version of libpng, but if you insert some they will be printed.
4524
4525VII. MNG support
4526
4527The MNG specification (available at http://www.libpng.org/pub/mng) allows
4528certain extensions to PNG for PNG images that are embedded in MNG datastreams.
4529Libpng can support some of these extensions.  To enable them, use the
4530png_permit_mng_features() function:
4531
4532   feature_set = png_permit_mng_features(png_ptr, mask)
4533
4534   mask is a png_uint_32 containing the bitwise OR of the
4535        features you want to enable.  These include
4536        PNG_FLAG_MNG_EMPTY_PLTE
4537        PNG_FLAG_MNG_FILTER_64
4538        PNG_ALL_MNG_FEATURES
4539
4540   feature_set is a png_uint_32 that is the bitwise AND of
4541      your mask with the set of MNG features that is
4542      supported by the version of libpng that you are using.
4543
4544It is an error to use this function when reading or writing a standalone
4545PNG file with the PNG 8-byte signature.  The PNG datastream must be wrapped
4546in a MNG datastream.  As a minimum, it must have the MNG 8-byte signature
4547and the MHDR and MEND chunks.  Libpng does not provide support for these
4548or any other MNG chunks; your application must provide its own support for
4549them.  You may wish to consider using libmng (available at
4550https://www.libmng.com/) instead.
4551
4552VIII. Changes to Libpng from version 0.88
4553
4554It should be noted that versions of libpng later than 0.96 are not
4555distributed by the original libpng author, Guy Schalnat, nor by
4556Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
4557distributed versions 0.89 through 0.96, but rather by another member
4558of the original PNG Group, Glenn Randers-Pehrson.  Guy and Andreas are
4559still alive and well, but they have moved on to other things.
4560
4561The old libpng functions png_read_init(), png_write_init(),
4562png_info_init(), png_read_destroy(), and png_write_destroy() have been
4563moved to PNG_INTERNAL in version 0.95 to discourage their use.  These
4564functions will be removed from libpng version 1.4.0.
4565
4566The preferred method of creating and initializing the libpng structures is
4567via the png_create_read_struct(), png_create_write_struct(), and
4568png_create_info_struct() because they isolate the size of the structures
4569from the application, allow version error checking, and also allow the
4570use of custom error handling routines during the initialization, which
4571the old functions do not.  The functions png_read_destroy() and
4572png_write_destroy() do not actually free the memory that libpng
4573allocated for these structs, but just reset the data structures, so they
4574can be used instead of png_destroy_read_struct() and
4575png_destroy_write_struct() if you feel there is too much system overhead
4576allocating and freeing the png_struct for each image read.
4577
4578Setting the error callbacks via png_set_message_fn() before
4579png_read_init() as was suggested in libpng-0.88 is no longer supported
4580because this caused applications that do not use custom error functions
4581to fail if the png_ptr was not initialized to zero.  It is still possible
4582to set the error callbacks AFTER png_read_init(), or to change them with
4583png_set_error_fn(), which is essentially the same function, but with a new
4584name to force compilation errors with applications that try to use the old
4585method.
4586
4587Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6;
4588however, iTXt support was not enabled by default.
4589
4590Starting with version 1.0.7, you can find out which version of the library
4591you are using at run-time:
4592
4593   png_uint_32 libpng_vn = png_access_version_number();
4594
4595The number libpng_vn is constructed from the major version, minor
4596version with leading zero, and release number with leading zero,
4597(e.g., libpng_vn for version 1.0.7 is 10007).
4598
4599Note that this function does not take a png_ptr, so you can call it
4600before you've created one.
4601
4602You can also check which version of png.h you used when compiling your
4603application:
4604
4605   png_uint_32 application_vn = PNG_LIBPNG_VER;
4606
4607IX. Changes to Libpng from version 1.0.x to 1.2.x
4608
4609Support for user memory management was enabled by default.  To
4610accomplish this, the functions png_create_read_struct_2(),
4611png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
4612png_malloc_default(), and png_free_default() were added.
4613
4614Support for the iTXt chunk has been enabled by default as of
4615version 1.2.41.
4616
4617Support for certain MNG features was enabled.
4618
4619Support for numbered error messages was added.  However, we never got
4620around to actually numbering the error messages.  The function
4621png_set_strip_error_numbers() was added (Note: the prototype for this
4622function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
4623builds of libpng-1.2.15.  It was restored in libpng-1.2.36).
4624
4625The png_malloc_warn() function was added at libpng-1.2.3.  This issues
4626a png_warning and returns NULL instead of aborting when it fails to
4627acquire the requested memory allocation.
4628
4629Support for setting user limits on image width and height was enabled
4630by default.  The functions png_set_user_limits(), png_get_user_width_max(),
4631and png_get_user_height_max() were added at libpng-1.2.6.
4632
4633The png_set_add_alpha() function was added at libpng-1.2.7.
4634
4635The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
4636Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
4637tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
4638deprecated.
4639
4640A number of macro definitions in support of runtime selection of
4641assembler code features (especially Intel MMX code support) were
4642added at libpng-1.2.0:
4643
4644    PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
4645    PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
4646    PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
4647    PNG_ASM_FLAG_MMX_READ_INTERLACE
4648    PNG_ASM_FLAG_MMX_READ_FILTER_SUB
4649    PNG_ASM_FLAG_MMX_READ_FILTER_UP
4650    PNG_ASM_FLAG_MMX_READ_FILTER_AVG
4651    PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
4652    PNG_ASM_FLAGS_INITIALIZED
4653    PNG_MMX_READ_FLAGS
4654    PNG_MMX_FLAGS
4655    PNG_MMX_WRITE_FLAGS
4656    PNG_MMX_FLAGS
4657
4658We added the following functions in support of runtime
4659selection of assembler code features:
4660
4661    png_get_mmx_flagmask()
4662    png_set_mmx_thresholds()
4663    png_get_asm_flags()
4664    png_get_mmx_bitdepth_threshold()
4665    png_get_mmx_rowbytes_threshold()
4666    png_set_asm_flags()
4667
4668We replaced all of these functions with simple stubs in libpng-1.2.20,
4669when the Intel assembler code was removed due to a licensing issue.
4670
4671These macros are deprecated:
4672
4673    PNG_READ_TRANSFORMS_NOT_SUPPORTED
4674    PNG_PROGRESSIVE_READ_NOT_SUPPORTED
4675    PNG_NO_SEQUENTIAL_READ_SUPPORTED
4676    PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
4677    PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
4678    PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
4679
4680They have been replaced, respectively, by:
4681
4682    PNG_NO_READ_TRANSFORMS
4683    PNG_NO_PROGRESSIVE_READ
4684    PNG_NO_SEQUENTIAL_READ
4685    PNG_NO_WRITE_TRANSFORMS
4686    PNG_NO_READ_ANCILLARY_CHUNKS
4687    PNG_NO_WRITE_ANCILLARY_CHUNKS
4688
4689PNG_MAX_UINT was replaced with PNG_UINT_31_MAX.  It has been
4690deprecated since libpng-1.0.16 and libpng-1.2.6.
4691
4692The function
4693    png_check_sig(sig, num)
4694was replaced with
4695    !png_sig_cmp(sig, 0, num)
4696It has been deprecated since libpng-0.90.
4697
4698The function
4699    png_set_gray_1_2_4_to_8()
4700which also expands tRNS to alpha was replaced with
4701    png_set_expand_gray_1_2_4_to_8()
4702which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
4703
4704X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
4705
4706Private libpng prototypes and macro definitions were moved from
4707png.h and pngconf.h into a new pngpriv.h header file.
4708
4709Functions png_set_benign_errors(), png_benign_error(), and
4710png_chunk_benign_error() were added.
4711
4712Support for setting the maximum amount of memory that the application
4713will allocate for reading chunks was added, as a security measure.
4714The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
4715were added to the library.
4716
4717We implemented support for I/O states by adding png_ptr member io_state
4718and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
4719
4720We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
4721input transforms.
4722
4723Checking for and reporting of errors in the IHDR chunk is more thorough.
4724
4725Support for global arrays was removed, to improve thread safety.
4726
4727Some obsolete/deprecated macros and functions have been removed.
4728
4729Typecasted NULL definitions such as
4730   #define png_voidp_NULL            (png_voidp)NULL
4731were eliminated.  If you used these in your application, just use
4732NULL instead.
4733
4734The png_struct and info_struct members "trans" and "trans_values" were
4735changed to "trans_alpha" and "trans_color", respectively.
4736
4737The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
4738were removed.
4739
4740The PNG_1_0_X and PNG_1_2_X macros were eliminated.
4741
4742The PNG_LEGACY_SUPPORTED macro was eliminated.
4743
4744Many WIN32_WCE #ifdefs were removed.
4745
4746The functions png_read_init(info_ptr), png_write_init(info_ptr),
4747png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
4748have been removed.  They have been deprecated since libpng-0.95.
4749
4750The png_permit_empty_plte() was removed. It has been deprecated
4751since libpng-1.0.9.  Use png_permit_mng_features() instead.
4752
4753We removed the obsolete stub functions png_get_mmx_flagmask(),
4754png_set_mmx_thresholds(), png_get_asm_flags(),
4755png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
4756png_set_asm_flags(), and png_mmx_supported()
4757
4758We removed the obsolete png_check_sig(), png_memcpy_check(), and
4759png_memset_check() functions.  Instead use !png_sig_cmp(), memcpy(),
4760and memset(), respectively.
4761
4762The function png_set_gray_1_2_4_to_8() was removed. It has been
4763deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
4764png_set_expand_gray_1_2_4_to_8() because the former function also
4765expanded any tRNS chunk to an alpha channel.
4766
4767Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
4768were added and are used by default instead of the corresponding
4769functions. Unfortunately,
4770from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
4771function) incorrectly returned a value of type png_uint_32.
4772
4773We changed the prototype for png_malloc() from
4774    png_malloc(png_structp png_ptr, png_uint_32 size)
4775to
4776    png_malloc(png_structp png_ptr, png_alloc_size_t size)
4777
4778This also applies to the prototype for the user replacement malloc_fn().
4779
4780The png_calloc() function was added and is used in place of
4781of "png_malloc(); memset();" except in the case in png_read_png()
4782where the array consists of pointers; in this case a "for" loop is used
4783after the png_malloc() to set the pointers to NULL, to give robust.
4784behavior in case the application runs out of memory part-way through
4785the process.
4786
4787We changed the prototypes of png_get_compression_buffer_size() and
4788png_set_compression_buffer_size() to work with size_t instead of
4789png_uint_32.
4790
4791Support for numbered error messages was removed by default, since we
4792never got around to actually numbering the error messages. The function
4793png_set_strip_error_numbers() was removed from the library by default.
4794
4795The png_zalloc() and png_zfree() functions are no longer exported.
4796The png_zalloc() function no longer zeroes out the memory that it
4797allocates.  Applications that called png_zalloc(png_ptr, number, size)
4798can call png_calloc(png_ptr, number*size) instead, and can call
4799png_free() instead of png_zfree().
4800
4801Support for dithering was disabled by default in libpng-1.4.0, because
4802it has not been well tested and doesn't actually "dither".
4803The code was not
4804removed, however, and could be enabled by building libpng with
4805PNG_READ_DITHER_SUPPORTED defined.  In libpng-1.4.2, this support
4806was re-enabled, but the function was renamed png_set_quantize() to
4807reflect more accurately what it actually does.  At the same time,
4808the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
4809PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
4810was renamed to PNG_READ_QUANTIZE_SUPPORTED.
4811
4812We removed the trailing '.' from the warning and error messages.
4813
4814XI. Changes to Libpng from version 1.4.x to 1.5.x
4815
4816From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
4817function) incorrectly returned a value of type png_uint_32.
4818The incorrect macro was removed from libpng-1.4.5.
4819
4820Checking for invalid palette index on write was added at libpng
48211.5.10.  If a pixel contains an invalid (out-of-range) index libpng issues
4822a benign error.  This is enabled by default because this condition is an
4823error according to the PNG specification, Clause 11.3.2, but the error can
4824be ignored in each png_ptr with
4825
4826   png_set_check_for_invalid_index(png_ptr, allowed);
4827
4828      allowed  - one of
4829                 0: disable benign error (accept the
4830                    invalid data without warning).
4831                 1: enable benign error (treat the
4832                    invalid data as an error or a
4833                    warning).
4834
4835If the error is ignored, or if png_benign_error() treats it as a warning,
4836any invalid pixels are decoded as opaque black by the decoder and written
4837as-is by the encoder.
4838
4839Retrieving the maximum palette index found was added at libpng-1.5.15.
4840This statement must appear after png_read_png() or png_read_image() while
4841reading, and after png_write_png() or png_write_image() while writing.
4842
4843   int max_palette = png_get_palette_max(png_ptr, info_ptr);
4844
4845This will return the maximum palette index found in the image, or "-1" if
4846the palette was not checked, or "0" if no palette was found.  Note that this
4847does not account for any palette index used by ancillary chunks such as the
4848bKGD chunk; you must check those separately to determine the maximum
4849palette index actually used.
4850
4851There are no substantial API changes between the non-deprecated parts of
4852the 1.4.5 API and the 1.5.0 API; however, the ability to directly access
4853members of the main libpng control structures, png_struct and png_info,
4854deprecated in earlier versions of libpng, has been completely removed from
4855libpng 1.5, and new private "pngstruct.h", "pnginfo.h", and "pngdebug.h"
4856header files were created.
4857
4858We no longer include zlib.h in png.h.  The include statement has been moved
4859to pngstruct.h, where it is not accessible by applications. Applications that
4860need access to information in zlib.h will need to add the '#include "zlib.h"'
4861directive.  It does not matter whether this is placed prior to or after
4862the '"#include png.h"' directive.
4863
4864The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used
4865and were removed.
4866
4867We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp()
4868macros into a private header file (pngpriv.h) that is not accessible to
4869applications.
4870
4871In png_get_iCCP, the type of "profile" was changed from png_charpp
4872to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
4873
4874There are changes of form in png.h, including new and changed macros to
4875declare parts of the API.  Some API functions with arguments that are
4876pointers to data not modified within the function have been corrected to
4877declare these arguments with const.
4878
4879Much of the internal use of C macros to control the library build has also
4880changed and some of this is visible in the exported header files, in
4881particular the use of macros to control data and API elements visible
4882during application compilation may require significant revision to
4883application code.  (It is extremely rare for an application to do this.)
4884
4885Any program that compiled against libpng 1.4 and did not use deprecated
4886features or access internal library structures should compile and work
4887against libpng 1.5, except for the change in the prototype for
4888png_get_iCCP() and png_set_iCCP() API functions mentioned above.
4889
4890libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
4891interlaced images.  The macros return the number of rows and columns in
4892each pass and information that can be used to de-interlace and (if
4893absolutely necessary) interlace an image.
4894
4895libpng 1.5.0 adds an API png_longjmp(png_ptr, value).  This API calls
4896the application-provided png_longjmp_ptr on the internal, but application
4897initialized, longjmp buffer.  It is provided as a convenience to avoid
4898the need to use the png_jmpbuf macro, which had the unnecessary side
4899effect of resetting the internal png_longjmp_ptr value.
4900
4901libpng 1.5.0 includes a complete fixed point API.  By default this is
4902present along with the corresponding floating point API.  In general the
4903fixed point API is faster and smaller than the floating point one because
4904the PNG file format used fixed point, not floating point.  This applies
4905even if the library uses floating point in internal calculations.  A new
4906macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
4907uses floating point arithmetic (the default) or fixed point arithmetic
4908internally for performance critical calculations such as gamma correction.
4909In some cases, the gamma calculations may produce slightly different
4910results.  This has changed the results in png_rgb_to_gray and in alpha
4911composition (png_set_background for example). This applies even if the
4912original image was already linear (gamma == 1.0) and, therefore, it is
4913not necessary to linearize the image.  This is because libpng has *not*
4914been changed to optimize that case correctly, yet.
4915
4916Fixed point support for the sCAL chunk comes with an important caveat;
4917the sCAL specification uses a decimal encoding of floating point values
4918and the accuracy of PNG fixed point values is insufficient for
4919representation of these values. Consequently a "string" API
4920(png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
4921arbitrary sCAL chunks in the absence of either the floating point API or
4922internal floating point calculations.  Starting with libpng-1.5.0, both
4923of these functions are present when PNG_sCAL_SUPPORTED is defined.  Prior
4924to libpng-1.5.0, their presence also depended upon PNG_FIXED_POINT_SUPPORTED
4925being defined and PNG_FLOATING_POINT_SUPPORTED not being defined.
4926
4927Applications no longer need to include the optional distribution header
4928file pngusr.h or define the corresponding macros during application
4929build in order to see the correct variant of the libpng API.  From 1.5.0
4930application code can check for the corresponding _SUPPORTED macro:
4931
4932#ifdef PNG_INCH_CONVERSIONS_SUPPORTED
4933   /* code that uses the inch conversion APIs. */
4934#endif
4935
4936This macro will only be defined if the inch conversion functions have been
4937compiled into libpng.  The full set of macros, and whether or not support
4938has been compiled in, are available in the header file pnglibconf.h.
4939This header file is specific to the libpng build.  Notice that prior to
49401.5.0 the _SUPPORTED macros would always have the default definition unless
4941reset by pngusr.h or by explicit settings on the compiler command line.
4942These settings may produce compiler warnings or errors in 1.5.0 because
4943of macro redefinition.
4944
4945Applications can now choose whether to use these macros or to call the
4946corresponding function by defining PNG_USE_READ_MACROS or
4947PNG_NO_USE_READ_MACROS before including png.h.  Notice that this is
4948only supported from 1.5.0; defining PNG_NO_USE_READ_MACROS prior to 1.5.0
4949will lead to a link failure.
4950
4951Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
4952when compressing the IDAT data and textual data such as zTXt and iCCP.
4953In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
4954We added five png_set_text_*() functions for setting the parameters to
4955use with textual data.
4956
4957Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
4958option was off by default, and slightly inaccurate scaling occurred.
4959This option can no longer be turned off, and the choice of accurate
4960or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8()
4961API for accurate scaling or the old png_set_strip_16_to_8() API for simple
4962chopping.  In libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
4963macro became PNG_READ_SCALE_16_TO_8_SUPPORTED, and the PNG_READ_16_TO_8
4964macro became PNG_READ_STRIP_16_TO_8_SUPPORTED, to enable the two
4965png_set_*_16_to_8() functions separately.
4966
4967Prior to libpng-1.5.4, the png_set_user_limits() function could only be
4968used to reduce the width and height limits from the value of
4969PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
4970that it could be used to override them.  Now this function will reduce or
4971increase the limits.
4972
4973Starting in libpng-1.5.22, default user limits were established. These
4974can be overridden by application calls to png_set_user_limits(),
4975png_set_user_chunk_cache_max(), and/or png_set_user_malloc_max().
4976The limits are now
4977                             max possible  default
4978   png_user_width_max        0x7fffffff    1,000,000
4979   png_user_height_max       0x7fffffff    1,000,000
4980   png_user_chunk_cache_max  0 (unlimited) 1000
4981   png_user_chunk_malloc_max 0 (unlimited) 8,000,000
4982
4983The png_set_option() function (and the "options" member of the png struct) was
4984added to libpng-1.5.15, with option PNG_ARM_NEON.
4985
4986The library now supports a complete fixed point implementation and can
4987thus be used on systems that have no floating point support or very
4988limited or slow support.  Previously gamma correction, an essential part
4989of complete PNG support, required reasonably fast floating point.
4990
4991As part of this the choice of internal implementation has been made
4992independent of the choice of fixed versus floating point APIs and all the
4993missing fixed point APIs have been implemented.
4994
4995The exact mechanism used to control attributes of API functions has
4996changed, as described in the INSTALL file.
4997
4998A new test program, pngvalid, is provided in addition to pngtest.
4999pngvalid validates the arithmetic accuracy of the gamma correction
5000calculations and includes a number of validations of the file format.
5001A subset of the full range of tests is run when "make check" is done
5002(in the 'configure' build.)  pngvalid also allows total allocated memory
5003usage to be evaluated and performs additional memory overwrite validation.
5004
5005Many changes to individual feature macros have been made. The following
5006are the changes most likely to be noticed by library builders who
5007configure libpng:
5008
50091) All feature macros now have consistent naming:
5010
5011#define PNG_NO_feature turns the feature off
5012#define PNG_feature_SUPPORTED turns the feature on
5013
5014pnglibconf.h contains one line for each feature macro which is either:
5015
5016#define PNG_feature_SUPPORTED
5017
5018if the feature is supported or:
5019
5020/*#undef PNG_feature_SUPPORTED*/
5021
5022if it is not.  Library code consistently checks for the 'SUPPORTED' macro.
5023It does not, and libpng applications should not, check for the 'NO' macro
5024which will not normally be defined even if the feature is not supported.
5025The 'NO' macros are only used internally for setting or not setting the
5026corresponding 'SUPPORTED' macros.
5027
5028Compatibility with the old names is provided as follows:
5029
5030PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
5031
5032And the following definitions disable the corresponding feature:
5033
5034PNG_SETJMP_NOT_SUPPORTED disables SETJMP
5035PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
5036PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
5037PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
5038PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
5039PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
5040
5041Library builders should remove use of the above, inconsistent, names.
5042
50432) Warning and error message formatting was previously conditional on
5044the STDIO feature. The library has been changed to use the
5045CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
5046the library no longer uses the printf(3) functions, even though the
5047default read/write implementations use (FILE) style stdio.h functions.
5048
50493) Three feature macros now control the fixed/floating point decisions:
5050
5051PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
5052
5053PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
5054practice these are normally required internally anyway (because the PNG
5055file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
5056merely stops the function from being exported.
5057
5058PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
5059point implementation or the fixed point one.  Typically the fixed point
5060implementation is larger and slower than the floating point implementation
5061on a system that supports floating point; however, it may be faster on a
5062system which lacks floating point hardware and therefore uses a software
5063emulation.
5064
50654) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED.  This allows the
5066functions to read and write ints to be disabled independently of
5067PNG_USE_READ_MACROS, which allows libpng to be built with the functions
5068even though the default is to use the macros - this allows applications
5069to choose at app buildtime whether or not to use macros (previously
5070impossible because the functions weren't in the default build.)
5071
5072XII. Changes to Libpng from version 1.5.x to 1.6.x
5073
5074A "simplified API" has been added (see documentation in png.h and a simple
5075example in contrib/examples/pngtopng.c).  The new publicly visible API
5076includes the following:
5077
5078   macros:
5079     PNG_FORMAT_*
5080     PNG_IMAGE_*
5081   structures:
5082     png_control
5083     png_image
5084   read functions
5085     png_image_begin_read_from_file()
5086     png_image_begin_read_from_stdio()
5087     png_image_begin_read_from_memory()
5088     png_image_finish_read()
5089     png_image_free()
5090   write functions
5091     png_image_write_to_file()
5092     png_image_write_to_memory()
5093     png_image_write_to_stdio()
5094
5095Starting with libpng-1.6.0, you can configure libpng to prefix all exported
5096symbols, using the PNG_PREFIX macro.
5097
5098We no longer include string.h in png.h.  The include statement has been moved
5099to pngpriv.h, where it is not accessible by applications.  Applications that
5100need access to information in string.h must add an '#include <string.h>'
5101directive.  It does not matter whether this is placed prior to or after
5102the '#include "png.h"' directive.
5103
5104The following API are now DEPRECATED:
5105   png_info_init_3()
5106   png_convert_to_rfc1123() which has been replaced
5107     with png_convert_to_rfc1123_buffer()
5108   png_malloc_default()
5109   png_free_default()
5110   png_reset_zstream()
5111
5112The following have been removed:
5113   png_get_io_chunk_name(), which has been replaced
5114     with png_get_io_chunk_type().  The new
5115     function returns a 32-bit integer instead of
5116     a string.
5117   The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and
5118     png_memset() macros are no longer used in the libpng sources and
5119     have been removed.  These had already been made invisible to applications
5120     (i.e., defined in the private pngpriv.h header file) since libpng-1.5.0.
5121
5122The signatures of many exported functions were changed, such that
5123   png_structp became png_structrp or png_const_structrp
5124   png_infop became png_inforp or png_const_inforp
5125where "rp" indicates a "restricted pointer".
5126
5127Dropped support for 16-bit platforms. The support for FAR/far types has
5128been eliminated and the definition of png_alloc_size_t is now controlled
5129by a flag so that 'small size_t' systems can select it if necessary.
5130
5131Error detection in some chunks has improved; in particular the iCCP chunk
5132reader now does pretty complete validation of the basic format.  Some bad
5133profiles that were previously accepted are now accepted with a warning or
5134rejected, depending upon the png_set_benign_errors() setting, in particular
5135the very old broken Microsoft/HP 3144-byte sRGB profile.  Starting with
5136libpng-1.6.11, recognizing and checking sRGB profiles can be avoided by
5137means of
5138
5139    #if defined(PNG_SKIP_sRGB_CHECK_PROFILE) && \
5140        defined(PNG_SET_OPTION_SUPPORTED)
5141       png_set_option(png_ptr, PNG_SKIP_sRGB_CHECK_PROFILE,
5142           PNG_OPTION_ON);
5143    #endif
5144
5145It's not a good idea to do this if you are using the "simplified API",
5146which needs to be able to recognize sRGB profiles conveyed via the iCCP
5147chunk.
5148
5149The PNG spec requirement that only grayscale profiles may appear in images
5150with color type 0 or 4 and that even if the image only contains gray pixels,
5151only RGB profiles may appear in images with color type 2, 3, or 6, is now
5152enforced.  The sRGB chunk is allowed to appear in images with any color type
5153and is interpreted by libpng to convey a one-tracer-curve gray profile or a
5154three-tracer-curve RGB profile as appropriate.
5155
5156Libpng 1.5.x erroneously used /MD for Debug DLL builds; if you used the debug
5157builds in your app and you changed your app to use /MD you will need to
5158change it back to /MDd for libpng 1.6.x.
5159
5160Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained
5161an empty language field or an empty translated keyword.  Both of these
5162are allowed by the PNG specification, so these warnings are no longer issued.
5163
5164The library now issues an error if the application attempts to set a
5165transform after it calls png_read_update_info() or if it attempts to call
5166both png_read_update_info() and png_start_read_image() or to call either
5167of them more than once.
5168
5169The default condition for benign_errors is now to treat benign errors as
5170warnings while reading and as errors while writing.
5171
5172The library now issues a warning if both background processing and RGB to
5173gray are used when gamma correction happens. As with previous versions of
5174the library the results are numerically very incorrect in this case.
5175
5176There are some minor arithmetic changes in some transforms such as
5177png_set_background(), that might be detected by certain regression tests.
5178
5179Unknown chunk handling has been improved internally, without any API change.
5180This adds more correct option control of the unknown handling, corrects
5181a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes
5182it possible to skip IDAT chunks in the sequential reader.
5183
5184The machine-generated configure files are no longer included in branches
5185libpng16 and later of the GIT repository.  They continue to be included
5186in the tarball releases, however.
5187
5188Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT
5189stream to set the size of the sliding window for reading instead of using the
5190default 32-kbyte sliding window size.  It was discovered that there are
5191hundreds of PNG files in the wild that have incorrect CMF bytes that caused
5192zlib to issue the "invalid distance too far back" error and reject the file.
5193Libpng-1.6.3 and later calculate their own safe CMF from the image dimensions,
5194provide a way to revert to the libpng-1.5.x behavior (ignoring the CMF bytes
5195and using a 32-kbyte sliding window), by using
5196
5197    png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW,
5198        PNG_OPTION_ON);
5199
5200and provide a tool (contrib/tools/pngfix) for rewriting a PNG file while
5201optimizing the CMF bytes in its IDAT chunk correctly.
5202
5203Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong
5204length, which resulted in PNG files that cannot be read beyond the bad iTXt
5205chunk.  This error was fixed in libpng-1.6.3, and a tool (called
5206contrib/tools/png-fix-itxt) has been added to the libpng distribution.
5207
5208Starting with libpng-1.6.17, the PNG_SAFE_LIMITS macro was eliminated
5209and safe limits are used by default (users who need larger limits
5210can still override them at compile time or run time, as described above).
5211
5212The new limits are
5213                                default   spec limit
5214   png_user_width_max         1,000,000  2,147,483,647
5215   png_user_height_max        1,000,000  2,147,483,647
5216   png_user_chunk_cache_max         128  unlimited
5217   png_user_chunk_malloc_max  8,000,000  unlimited
5218
5219Starting with libpng-1.6.18, a PNG_RELEASE_BUILD macro was added, which allows
5220library builders to control compilation for an installed system (a release build).
5221It can be set for testing debug or beta builds to ensure that they will compile
5222when the build type is switched to RC or STABLE. In essence this overrides the
5223PNG_LIBPNG_BUILD_BASE_TYPE definition which is not directly user controllable.
5224
5225Starting with libpng-1.6.19, attempting to set an over-length PLTE chunk
5226is an error. Previously this requirement of the PNG specification was not
5227enforced, and the palette was always limited to 256 entries. An over-length
5228PLTE chunk found in an input PNG is silently truncated.
5229
5230Starting with libpng-1.6.31, the eXIf chunk is supported. Libpng does not
5231attempt to decode the Exif profile; it simply returns a byte array
5232containing the profile to the calling application which must do its own
5233decoding.
5234
5235XIII. Detecting libpng
5236
5237The png_get_io_ptr() function has been present since libpng-0.88, has never
5238changed, and is unaffected by conditional compilation macros.  It is the
5239best choice for use in configure scripts for detecting the presence of any
5240libpng version since 0.88.  In an autoconf "configure.in" you could use
5241
5242    AC_CHECK_LIB(png, png_get_io_ptr, ...
5243
5244XV. Source code repository
5245
5246Since about February 2009, version 1.2.34, libpng has been under "git" source
5247control.  The git repository was built from old libpng-x.y.z.tar.gz files
5248going back to version 0.70.  You can access the git repository (read only)
5249at
5250
5251    https://github.com/glennrp/libpng or
5252    https://git.code.sf.net/p/libpng/code.git
5253
5254or you can browse it with a web browser at
5255
5256    https://github.com/glennrp/libpng or
5257    https://sourceforge.net/p/libpng/code/ci/libpng16/tree/
5258
5259Patches can be sent to png-mng-implement at lists.sourceforge.net or
5260uploaded to the libpng bug tracker at
5261
5262    https://libpng.sourceforge.io/
5263
5264or as a "pull request" to
5265
5266    https://github.com/glennrp/libpng/pulls
5267
5268We also accept patches built from the tar or zip distributions, and
5269simple verbal descriptions of bug fixes, reported either to the
5270SourceForge bug tracker, to the png-mng-implement at lists.sf.net
5271mailing list, as github issues.
5272
5273XV. Coding style
5274
5275Our coding style is similar to the "Allman" style
5276(See https://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly
5277braces on separate lines:
5278
5279    if (condition)
5280    {
5281       action;
5282    }
5283
5284    else if (another condition)
5285    {
5286       another action;
5287    }
5288
5289The braces can be omitted from simple one-line actions:
5290
5291    if (condition)
5292       return 0;
5293
5294We use 3-space indentation, except for continued statements which
5295are usually indented the same as the first line of the statement
5296plus four more spaces.
5297
5298For macro definitions we use 2-space indentation, always leaving the "#"
5299in the first column.
5300
5301    #ifndef PNG_NO_FEATURE
5302    #  ifndef PNG_FEATURE_SUPPORTED
5303    #    define PNG_FEATURE_SUPPORTED
5304    #  endif
5305    #endif
5306
5307Comments appear with the leading "/*" at the same indentation as
5308the statement that follows the comment:
5309
5310    /* Single-line comment */
5311    statement;
5312
5313    /* This is a multiple-line
5314     * comment.
5315     */
5316    statement;
5317
5318Very short comments can be placed after the end of the statement
5319to which they pertain:
5320
5321    statement;    /* comment */
5322
5323We don't use C++ style ("//") comments. We have, however,
5324used them in the past in some now-abandoned MMX assembler
5325code.
5326
5327Functions and their curly braces are not indented, and
5328exported functions are marked with PNGAPI:
5329
5330 /* This is a public function that is visible to
5331  * application programmers. It does thus-and-so.
5332  */
5333 void PNGAPI
5334 png_exported_function(png_ptr, png_info, foo)
5335 {
5336    body;
5337 }
5338
5339The return type and decorations are placed on a separate line
5340ahead of the function name, as illustrated above.
5341
5342The prototypes for all exported functions appear in png.h,
5343above the comment that says
5344
5345    /* Maintainer: Put new public prototypes here ... */
5346
5347We mark all non-exported functions with "/* PRIVATE */"":
5348
5349 void /* PRIVATE */
5350 png_non_exported_function(png_ptr, png_info, foo)
5351 {
5352    body;
5353 }
5354
5355The prototypes for non-exported functions (except for those in
5356pngtest) appear in pngpriv.h above the comment that says
5357
5358  /* Maintainer: Put new private prototypes here ^ */
5359
5360To avoid polluting the global namespace, the names of all exported
5361functions and variables begin with "png_", and all publicly visible C
5362preprocessor macros begin with "PNG".  We request that applications that
5363use libpng *not* begin any of their own symbols with either of these strings.
5364
5365We put a space after the "sizeof" operator and we omit the
5366optional parentheses around its argument when the argument
5367is an expression, not a type name, and we always enclose the
5368sizeof operator, with its argument, in parentheses:
5369
5370  (sizeof (png_uint_32))
5371  (sizeof array)
5372
5373Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as
5374though it were a function.
5375
5376Control keywords if, for, while, and switch are always followed by a space
5377to distinguish them from function calls, which have no trailing space.
5378
5379We put a space after each comma and after each semicolon
5380in "for" statements, and we put spaces before and after each
5381C binary operator and after "for" or "while", and before
5382"?".  We don't put a space between a typecast and the expression
5383being cast, nor do we put one between a function name and the
5384left parenthesis that follows it:
5385
5386    for (i = 2; i > 0; --i)
5387       y[i] = a(x) + (int)b;
5388
5389We prefer #ifdef and #ifndef to #if defined() and #if !defined()
5390when there is only one macro being tested.  We always use parentheses
5391with "defined".
5392
5393We express integer constants that are used as bit masks in hex format,
5394with an even number of lower-case hex digits, and to make them unsigned
5395(e.g., 0x00U, 0xffU, 0x0100U) and long if they are greater than 0x7fff
5396(e.g., 0xffffUL).
5397
5398We prefer to use underscores rather than camelCase in names, except
5399for a few type names that we inherit from zlib.h.
5400
5401We prefer "if (something != 0)" and "if (something == 0)" over
5402"if (something)" and if "(!something)", respectively, and for pointers
5403we prefer "if (some_pointer != NULL)" or "if (some_pointer == NULL)".
5404
5405We do not use the TAB character for indentation in the C sources.
5406
5407Lines do not exceed 80 characters.
5408
5409Other rules can be inferred by inspecting the libpng source.
5410