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