1 Libpng-manual.txt - A description on how to use and modify libpng
3 libpng version 1.5.14 - January 24, 2013
4 Updated and distributed by Glenn Randers-Pehrson
5 <glennrp at users.sourceforge.net>
6 Copyright (c) 1998-2012 Glenn Randers-Pehrson
8 This document is released under the libpng license.
9 For conditions of distribution and use, see the disclaimer
14 libpng versions 0.97, January 1998, through 1.5.14 - January 24, 2013
15 Updated and distributed by Glenn Randers-Pehrson
16 Copyright (c) 1998-2012 Glenn Randers-Pehrson
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
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.
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
33 This file describes how to use and modify the PNG reference library
34 (known as libpng) for your own use. There are five sections to this
35 file: introduction, structures, reading, writing, and modification and
36 configuration notes for various special platforms. In addition to this
37 file, example.c is a good starting point for using the library, as
38 it is heavily commented and should include everything most people
39 will need. We assume that libpng is already installed; see the
40 INSTALL file for instructions on how to install libpng.
42 For examples of libpng usage, see the files "example.c", "pngtest.c",
43 and the files in the "contrib" directory, all of which are included in
44 the libpng distribution.
46 Libpng was written as a companion to the PNG specification, as a way
47 of reducing the amount of time and effort it takes to support the PNG
48 file format in application programs.
50 The PNG specification (second edition), November 2003, is available as
51 a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at
52 <http://www.w3.org/TR/2003/REC-PNG-20031110/
53 The W3C and ISO documents have identical technical content.
55 The PNG-1.2 specification is available at
56 <http://www.libpng.org/pub/png/documents/>. It is technically equivalent
57 to the PNG specification (second edition) but has some additional material.
59 The PNG-1.0 specification is available
60 as RFC 2083 <http://www.libpng.org/pub/png/documents/> and as a
61 W3C Recommendation <http://www.w3.org/TR/REC.png.html>.
63 Some additional chunks are described in the special-purpose public chunks
64 documents at <http://www.libpng.org/pub/png/documents/>.
67 about PNG, and the latest version of libpng, can be found at the PNG home
68 page, <http://www.libpng.org/pub/png/>.
70 Most users will not have to modify the library significantly; advanced
71 users may want to modify it more. All attempts were made to make it as
72 complete as possible, while keeping the code easy to understand.
73 Currently, this library only supports C. Support for other languages
76 Libpng has been designed to handle multiple sessions at one time,
77 to be easily modifiable, to be portable to the vast majority of
78 machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy
79 to use. The ultimate goal of libpng is to promote the acceptance of
80 the PNG file format in whatever way possible. While there is still
81 work to be done (see the TODO file), libpng should cover the
82 majority of the needs of its users.
84 Libpng uses zlib for its compression and decompression of PNG files.
85 Further information about zlib, and the latest version of zlib, can
86 be found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.
87 The zlib compression utility is a general purpose utility that is
88 useful for more than PNG files, and can be used without libpng.
89 See the documentation delivered with zlib for more details.
90 You can usually find the source files for the zlib utility wherever you
91 find the libpng source files.
93 Libpng is thread safe, provided the threads are using different
94 instances of the structures. Each thread should have its own
95 png_struct and png_info instances, and thus its own image.
96 Libpng does not protect itself against two threads using the
97 same instance of a structure.
101 There are two main structures that are important to libpng, png_struct
102 and png_info. Both are internal structures that are no longer exposed
103 in the libpng interface (as of libpng 1.5.0).
105 The png_info structure is designed to provide information about the
106 PNG file. At one time, the fields of png_info were intended to be
107 directly accessible to the user. However, this tended to cause problems
108 with applications using dynamically loaded libraries, and as a result
109 a set of interface functions for png_info (the png_get_*() and png_set_*()
110 functions) was developed, and direct access to the png_info fields was
113 The png_struct structure is the object used by the library to decode a
114 single image. As of 1.5.0 this structure is also not exposed.
116 Almost all libpng APIs require a pointer to a png_struct as the first argument.
117 Many (in particular the png_set and png_get APIs) also require a pointer
118 to png_info as the second argument. Some application visible macros
119 defined in png.h designed for basic data access (reading and writing
120 integers in the PNG format) don't take a png_info pointer, but it's almost
121 always safe to assume that a (png_struct*) has to be passed to call an API
124 You can have more than one png_info structure associated with an image,
125 as illustrated in pngtest.c, one for information valid prior to the
126 IDAT chunks and another (called "end_info" below) for things after them.
128 The png.h header file is an invaluable reference for programming with libpng.
129 And while I'm on the topic, make sure you include the libpng header file:
133 and also (as of libpng-1.5.0) the zlib header file, if you need it:
139 The png.h header file defines a number of integral types used by the
140 APIs. Most of these are fairly obvious; for example types corresponding
141 to integers of particular sizes and types for passing color values.
143 One exception is how non-integral numbers are handled. For application
144 convenience most APIs that take such numbers have C (double) arguments;
145 however, internally PNG, and libpng, use 32 bit signed integers and encode
146 the value by multiplying by 100,000. As of libpng 1.5.0 a convenience
147 macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point)
148 which is simply (png_int_32).
150 All APIs that take (double) arguments also have a matching API that
151 takes the corresponding fixed point integer arguments. The fixed point
152 API has the same name as the floating point one with "_fixed" appended.
153 The actual range of values permitted in the APIs is frequently less than
154 the full range of (png_fixed_point) (-21474 to +21474). When APIs require
155 a non-negative argument the type is recorded as png_uint_32 above. Consult
156 the header file and the text below for more information.
158 Special care must be take with sCAL chunk handling because the chunk itself
159 uses non-integral values encoded as strings containing decimal floating point
160 numbers. See the comments in the header file.
164 The main header file function declarations are frequently protected by C
165 preprocessing directives of the form:
167 #ifdef PNG_feature_SUPPORTED
171 #ifdef PNG_feature_SUPPORTED
175 The library can be built without support for these APIs, although a
176 standard build will have all implemented APIs. Application programs
177 should check the feature macros before using an API for maximum
178 portability. From libpng 1.5.0 the feature macros set during the build
179 of libpng are recorded in the header file "pnglibconf.h" and this file
180 is always included by png.h.
182 If you don't need to change the library configuration from the default, skip to
183 the next section ("Reading").
185 Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all
186 of the build project files in the 'projects' directory simply copy
187 scripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these build
188 systems do not permit easy auto-configuration of the library - they only
189 support the default configuration.
191 The easiest way to make minor changes to the libpng configuration when
192 auto-configuration is supported is to add definitions to the command line
193 using (typically) CPPFLAGS. For example:
195 CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC
197 will change the internal libpng math implementation for gamma correction and
198 other arithmetic calculations to fixed point, avoiding the need for fast
199 floating point support. The result can be seen in the generated pnglibconf.h -
200 make sure it contains the changed feature macro setting.
202 If you need to make more extensive configuration changes - more than one or two
203 feature macro settings - you can either add -DPNG_USER_CONFIG to the build
204 command line and put a list of feature macro settings in pngusr.h or you can set
205 DFA_XTRA (a makefile variable) to a file containing the same information in the
206 form of 'option' settings.
208 A. Changing pnglibconf.h
210 A variety of methods exist to build libpng. Not all of these support
211 reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be
212 rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand.
214 Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to
215 pnglibconf.h and changing the lines defining the supported features, paying
216 very close attention to the 'option' information in scripts/pnglibconf.dfa
217 that describes those features and their requirements. This is easy to get
220 B. Configuration using DFA_XTRA
222 Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later
223 variant such as 'nawk' or 'gawk', is available. The configure build will
224 automatically find an appropriate awk and build pnglibconf.h.
225 The scripts/pnglibconf.mak file contains a set of make rules for doing the
226 same thing if configure is not used, and many of the makefiles in the scripts
227 directory use this approach.
229 When rebuilding simply write a new file containing changed options and set
230 DFA_XTRA to the name of this file. This causes the build to append the new file
231 to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines
232 of the following forms:
236 This turns all optional features off. Include it at the start of pngusr.dfa to
237 make it easier to build a minimal configuration. You will need to turn at least
238 some features on afterward to enable either reading or writing code, or both.
243 Enable or disable a single feature. This will automatically enable other
244 features required by a feature that is turned on or disable other features that
245 require a feature which is turned off. Conflicting settings will cause an error
246 message to be emitted by awk.
248 setting feature default value
250 Changes the default value of setting 'feature' to 'value'. There are a small
251 number of settings listed at the top of pnglibconf.h, they are documented in the
252 source code. Most of these values have performance implications for the library
253 but most of them have no visible effect on the API. Some can also be overridden
256 This method of building a customized pnglibconf.h is illustrated in
257 contrib/pngminim/*. See the "$(PNGCONF):" target in the makefile and
258 pngusr.dfa in these directories.
260 C. Configuration using PNG_USR_CONFIG
262 If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file
263 pngusr.h will automatically be included before the options in
264 scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only
265 macro definitions turning features on or off or setting settings.
267 Apart from the global setting "everything = off" all the options listed above
268 can be set using macros in pngusr.h:
270 #define PNG_feature_SUPPORTED
276 #define PNG_NO_feature
282 #define PNG_feature value
286 setting feature default value
288 Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the
289 pngusr file you supply override the contents of scripts/pnglibconf.dfa
291 If confusing or incomprehensible behavior results it is possible to
292 examine the intermediate file pnglibconf.dfn to find the full set of
293 dependency information for each setting and option. Simply locate the
294 feature in the file and read the C comments that precede it.
296 This method is also illustrated in the contrib/pngminim/* makefiles and
301 We'll now walk you through the possible functions to call when reading
302 in a PNG file sequentially, briefly explaining the syntax and purpose
303 of each one. See example.c and png.h for more detail. While
304 progressive reading is covered in the next section, you will still
305 need some of the functions discussed in this section to read a PNG
310 You will want to do the I/O initialization(*) before you get into libpng,
311 so if it doesn't work, you don't have much to undo. Of course, you
312 will also want to insure that you are, in fact, dealing with a PNG
313 file. Libpng provides a simple check to see if a file is a PNG file.
314 To use it, pass in the first 1 to 8 bytes of the file to the function
315 png_sig_cmp(), and it will return 0 (false) if the bytes match the
316 corresponding bytes of the PNG signature, or nonzero (true) otherwise.
317 Of course, the more bytes you pass in, the greater the accuracy of the
320 If you are intending to keep the file pointer open for use in libpng,
321 you must ensure you don't read more than 8 bytes from the beginning
322 of the file, and you also have to make a call to png_set_sig_bytes_read()
323 with the number of bytes you read from the beginning. Libpng will
324 then only check the bytes (if any) that your program didn't read.
326 (*): If you are not using the standard I/O functions, you will need
327 to replace them with custom functions. See the discussion under
331 FILE *fp = fopen(file_name, "rb");
337 fread(header, 1, number, fp);
338 is_png = !png_sig_cmp(header, 0, number);
346 Next, png_struct and png_info need to be allocated and initialized. In
347 order to ensure that the size of these structures is correct even with a
348 dynamically linked libpng, there are functions to initialize and
349 allocate the structures. We also pass the library version, optional
350 pointers to error handling functions, and a pointer to a data struct for
351 use by the error functions, if necessary (the pointer and functions can
352 be NULL if the default error handlers are to be used). See the section
353 on Changes to Libpng below regarding the old initialization functions.
354 The structure allocation functions quietly return NULL if they fail to
355 create the structure, so your application should check for that.
357 png_structp png_ptr = png_create_read_struct
358 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
359 user_error_fn, user_warning_fn);
364 png_infop info_ptr = png_create_info_struct(png_ptr);
368 png_destroy_read_struct(&png_ptr,
369 (png_infopp)NULL, (png_infopp)NULL);
373 If you want to use your own memory allocation routines,
374 use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, and use
375 png_create_read_struct_2() instead of png_create_read_struct():
377 png_structp png_ptr = png_create_read_struct_2
378 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
379 user_error_fn, user_warning_fn, (png_voidp)
380 user_mem_ptr, user_malloc_fn, user_free_fn);
382 The error handling routines passed to png_create_read_struct()
383 and the memory alloc/free routines passed to png_create_struct_2()
384 are only necessary if you are not using the libpng supplied error
385 handling and memory alloc/free functions.
387 When libpng encounters an error, it expects to longjmp back
388 to your routine. Therefore, you will need to call setjmp and pass
389 your png_jmpbuf(png_ptr). If you read the file from different
390 routines, you will need to update the longjmp buffer every time you enter
391 a new routine that will call a png_*() function.
393 See your documentation of setjmp/longjmp for your compiler for more
394 information on setjmp/longjmp. See the discussion on libpng error
395 handling in the Customizing Libpng section below for more information
396 on the libpng error handling. If an error occurs, and libpng longjmp's
397 back to your setjmp, you will want to call png_destroy_read_struct() to
400 if (setjmp(png_jmpbuf(png_ptr)))
402 png_destroy_read_struct(&png_ptr, &info_ptr,
408 Pass (png_infopp)NULL instead of &end_info if you didn't create
409 an end_info structure.
411 If you would rather avoid the complexity of setjmp/longjmp issues,
412 you can compile libpng with PNG_NO_SETJMP, in which case
413 errors will result in a call to PNG_ABORT() which defaults to abort().
415 You can #define PNG_ABORT() to a function that does something
416 more useful than abort(), as long as your function does not
419 Now you need to set up the input code. The default for libpng is to
420 use the C function fread(). If you use this, you will need to pass a
421 valid FILE * in the function png_init_io(). Be sure that the file is
422 opened in binary mode. If you wish to handle reading data in another
423 way, you need not call the png_init_io() function, but you must then
424 implement the libpng I/O methods discussed in the Customizing Libpng
427 png_init_io(png_ptr, fp);
429 If you had previously opened the file and read any of the signature from
430 the beginning in order to see if this was a PNG file, you need to let
431 libpng know that there are some bytes missing from the start of the file.
433 png_set_sig_bytes(png_ptr, number);
435 You can change the zlib compression buffer size to be used while
436 reading compressed data with
438 png_set_compression_buffer_size(png_ptr, buffer_size);
440 where the default size is 8192 bytes. Note that the buffer size
441 is changed immediately and the buffer is reallocated immediately,
442 instead of setting a flag to be acted upon later.
444 If you want CRC errors to be handled in a different manner than
447 png_set_crc_action(png_ptr, crit_action, ancil_action);
449 The values for png_set_crc_action() say how libpng is to handle CRC errors in
450 ancillary and critical chunks, and whether to use the data contained
451 therein. Note that it is impossible to "discard" data in a critical
454 Choices for (int) crit_action are
455 PNG_CRC_DEFAULT 0 error/quit
456 PNG_CRC_ERROR_QUIT 1 error/quit
457 PNG_CRC_WARN_USE 3 warn/use data
458 PNG_CRC_QUIET_USE 4 quiet/use data
459 PNG_CRC_NO_CHANGE 5 use the current value
461 Choices for (int) ancil_action are
462 PNG_CRC_DEFAULT 0 error/quit
463 PNG_CRC_ERROR_QUIT 1 error/quit
464 PNG_CRC_WARN_DISCARD 2 warn/discard data
465 PNG_CRC_WARN_USE 3 warn/use data
466 PNG_CRC_QUIET_USE 4 quiet/use data
467 PNG_CRC_NO_CHANGE 5 use the current value
469 Setting up callback code
471 You can set up a callback function to handle any unknown chunks in the
472 input stream. You must supply the function
474 read_chunk_callback(png_structp png_ptr,
475 png_unknown_chunkp chunk);
477 /* The unknown chunk structure contains your
478 chunk data, along with similar data for any other
485 /* Note that libpng has already taken care of
488 /* put your code here. Search for your chunk in the
489 unknown chunk structure, process it, and return one
492 return (-n); /* chunk had an error */
493 return (0); /* did not recognize */
494 return (n); /* success */
497 (You can give your function another name that you like instead of
498 "read_chunk_callback")
500 To inform libpng about your function, use
502 png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,
503 read_chunk_callback);
505 This names not only the callback function, but also a user pointer that
506 you can retrieve with
508 png_get_user_chunk_ptr(png_ptr);
510 If you call the png_set_read_user_chunk_fn() function, then all unknown
511 chunks will be saved when read, in case your callback function will need
512 one or more of them. This behavior can be changed with the
513 png_set_keep_unknown_chunks() function, described below.
515 At this point, you can set up a callback function that will be
516 called after each row has been read, which you can use to control
517 a progress meter or the like. It's demonstrated in pngtest.c.
518 You must supply a function
520 void read_row_callback(png_structp png_ptr,
521 png_uint_32 row, int pass);
523 /* put your code here */
526 (You can give it another name that you like instead of "read_row_callback")
528 To inform libpng about your function, use
530 png_set_read_status_fn(png_ptr, read_row_callback);
532 When this function is called the row has already been completely processed and
533 the 'row' and 'pass' refer to the next row to be handled. For the
534 non-interlaced case the row that was just handled is simply one less than the
535 passed in row number, and pass will always be 0. For the interlaced case the
536 same applies unless the row value is 0, in which case the row just handled was
537 the last one from one of the preceding passes. Because interlacing may skip a
538 pass you cannot be sure that the preceding pass is just 'pass-1', if you really
539 need to know what the last pass is record (row,pass) from the callback and use
540 the last recorded value each time.
542 As with the user transform you can find the output row using the
543 PNG_ROW_FROM_PASS_ROW macro.
545 Unknown-chunk handling
547 Now you get to set the way the library processes unknown chunks in the
548 input PNG stream. Both known and unknown chunks will be read. Normal
549 behavior is that known chunks will be parsed into information in
550 various info_ptr members while unknown chunks will be discarded. This
551 behavior can be wasteful if your application will never use some known
552 chunk types. To change this, you can call:
554 png_set_keep_unknown_chunks(png_ptr, keep,
555 chunk_list, num_chunks);
556 keep - 0: default unknown chunk handling
557 1: ignore; do not keep
558 2: keep only if safe-to-copy
559 3: keep even if unsafe-to-copy
561 You can use these definitions:
562 PNG_HANDLE_CHUNK_AS_DEFAULT 0
563 PNG_HANDLE_CHUNK_NEVER 1
564 PNG_HANDLE_CHUNK_IF_SAFE 2
565 PNG_HANDLE_CHUNK_ALWAYS 3
567 chunk_list - list of chunks affected (a byte string,
568 five bytes per chunk, NULL or '\0' if
571 num_chunks - number of chunks affected; if 0, all
572 unknown chunks are affected. If nonzero,
573 only the chunks in the list are affected
575 Unknown chunks declared in this way will be saved as raw data onto a
576 list of png_unknown_chunk structures. If a chunk that is normally
577 known to libpng is named in the list, it will be handled as unknown,
578 according to the "keep" directive. If a chunk is named in successive
579 instances of png_set_keep_unknown_chunks(), the final instance will
580 take precedence. The IHDR and IEND chunks should not be named in
581 chunk_list; if they are, libpng will process them normally anyway.
582 If you know that your application will never make use of some particular
583 chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below.
585 Here is an example of the usage of png_set_keep_unknown_chunks(),
586 where the private "vpAg" chunk will later be processed by a user chunk
589 png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'};
591 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
592 png_byte unused_chunks[]=
594 104, 73, 83, 84, (png_byte) '\0', /* hIST */
595 105, 84, 88, 116, (png_byte) '\0', /* iTXt */
596 112, 67, 65, 76, (png_byte) '\0', /* pCAL */
597 115, 67, 65, 76, (png_byte) '\0', /* sCAL */
598 115, 80, 76, 84, (png_byte) '\0', /* sPLT */
599 116, 73, 77, 69, (png_byte) '\0', /* tIME */
605 #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED)
606 /* ignore all unknown chunks: */
607 png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0);
609 /* except for vpAg: */
610 png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1);
612 /* also ignore unused known chunks: */
613 png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks,
614 (int)sizeof(unused_chunks)/5);
619 The PNG specification allows the width and height of an image to be as
620 large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns.
621 Since very few applications really need to process such large images,
622 we have imposed an arbitrary 1-million limit on rows and columns.
623 Larger images will be rejected immediately with a png_error() call. If
624 you wish to change this limit, you can use
626 png_set_user_limits(png_ptr, width_max, height_max);
628 to set your own limits, or use width_max = height_max = 0x7fffffffL
629 to allow all valid dimensions (libpng may reject some very large images
630 anyway because of potential buffer overflow conditions).
632 You should put this statement after you create the PNG structure and
633 before calling png_read_info(), png_read_png(), or png_process_data().
635 When writing a PNG datastream, put this statement before calling
636 png_write_info() or png_write_png().
638 If you need to retrieve the limits that are being applied, use
640 width_max = png_get_user_width_max(png_ptr);
641 height_max = png_get_user_height_max(png_ptr);
643 The PNG specification sets no limit on the number of ancillary chunks
644 allowed in a PNG datastream. You can impose a limit on the total number
645 of sPLT, tEXt, iTXt, zTXt, and unknown chunks that will be stored, with
647 png_set_chunk_cache_max(png_ptr, user_chunk_cache_max);
649 where 0x7fffffffL means unlimited. You can retrieve this limit with
651 chunk_cache_max = png_get_chunk_cache_max(png_ptr);
653 You can also set a limit on the amount of memory that a compressed chunk
654 other than IDAT can occupy, with
656 png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max);
658 and you can retrieve the limit with
660 chunk_malloc_max = png_get_chunk_malloc_max(png_ptr);
662 Any chunks that would cause either of these limits to be exceeded will
665 Information about your system
667 If you intend to display the PNG or to incorporate it in other image data you
668 need to tell libpng information about your display or drawing surface so that
669 libpng can convert the values in the image to match the display.
671 From libpng-1.5.4 this information can be set before reading the PNG file
672 header. In earlier versions png_set_gamma() existed but behaved incorrectly if
673 called before the PNG file header had been read and png_set_alpha_mode() did not
676 If you need to support versions prior to libpng-1.5.4 test the version number
677 as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures
678 described in the appropriate manual page.
680 You give libpng the encoding expected by your system expressed as a 'gamma'
681 value. You can also specify a default encoding for the PNG file in
682 case the required information is missing from the file. By default libpng
683 assumes that the PNG data matches your system, to keep this default call:
685 png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/);
687 or you can use the fixed point equivalent:
689 png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_gamma);
691 If you don't know the gamma for your system it is probably 2.2 - a good
692 approximation to the IEC standard for display systems (sRGB). If images are
693 too contrasty or washed out you got the value wrong - check your system
696 Many systems permit the system gamma to be changed via a lookup table in the
697 display driver, a few systems, including older Macs, change the response by
698 default. As of 1.5.4 three special values are available to handle common
701 PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1
702 standard. This matches almost all systems.
703 PNG_GAMMA_MAC_18: Indicates that the system is an older (pre Mac OS 10.6)
704 Apple Macintosh system with the default settings.
705 PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates that the
706 system expects data with no gamma encoding.
708 You would use the linear (unencoded) value if you need to process the pixel
709 values further because this avoids the need to decode and reencode each
710 component value whenever arithmetic is performed. A lot of graphics software
711 uses linear values for this reason, often with higher precision component values
712 to preserve overall accuracy.
714 The second thing you may need to tell libpng about is how your system handles
715 alpha channel information. Some, but not all, PNG files contain an alpha
716 channel. To display these files correctly you need to compose the data onto a
717 suitable background, as described in the PNG specification.
719 Libpng only supports composing onto a single color (using png_set_background;
720 see below). Otherwise you must do the composition yourself and, in this case,
721 you may need to call png_set_alpha_mode:
723 #if PNG_LIBPNG_VER >= 10504
724 png_set_alpha_mode(png_ptr, mode, screen_gamma);
726 png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma);
729 The screen_gamma value is the same as the argument to png_set_gamma; however,
730 how it affects the output depends on the mode. png_set_alpha_mode() sets the
731 file gamma default to 1/screen_gamma, so normally you don't need to call
732 png_set_gamma. If you need different defaults call png_set_gamma() before
733 png_set_alpha_mode() - if you call it after it will override the settings made
734 by png_set_alpha_mode().
736 The mode is as follows:
738 PNG_ALPHA_PNG: The data is encoded according to the PNG specification. Red,
739 green and blue, or gray, components are gamma encoded color
740 values and are not premultiplied by the alpha value. The
741 alpha value is a linear measure of the contribution of the
742 pixel to the corresponding final output pixel.
744 You should normally use this format if you intend to perform
745 color correction on the color values; most, maybe all, color
746 correction software has no handling for the alpha channel and,
747 anyway, the math to handle pre-multiplied component values is
748 unnecessarily complex.
750 Before you do any arithmetic on the component values you need
751 to remove the gamma encoding and multiply out the alpha
752 channel. See the PNG specification for more detail. It is
753 important to note that when an image with an alpha channel is
754 scaled, linear encoded, pre-multiplied component values must
757 The remaining modes assume you don't need to do any further color correction or
758 that if you do, your color correction software knows all about alpha (it
761 PNG_ALPHA_STANDARD: The data libpng produces
762 is encoded in the standard way
763 assumed by most correctly written graphics software.
764 The gamma encoding will be removed by libpng and the
765 linear component values will be pre-multiplied by the
768 With this format the final image must be re-encoded to
769 match the display gamma before the image is displayed.
770 If your system doesn't do that, yet still seems to
771 perform arithmetic on the pixels without decoding them,
772 it is broken - check out the modes below.
774 With PNG_ALPHA_STANDARD libpng always produces linear
775 component values, whatever screen_gamma you supply. The
776 screen_gamma value is, however, used as a default for
777 the file gamma if the PNG file has no gamma information.
779 If you call png_set_gamma() after png_set_alpha_mode() you
780 will override the linear encoding. Instead the
781 pre-multiplied pixel values will be gamma encoded but
782 the alpha channel will still be linear. This may
783 actually match the requirements of some broken software,
786 While linear 8-bit data is often used it has
787 insufficient precision for any image with a reasonable
788 dynamic range. To avoid problems, and if your software
789 supports it, use png_set_expand_16() to force all
790 components to 16 bits.
792 PNG_ALPHA_OPTIMIZED: This mode is the same
793 as PNG_ALPHA_STANDARD except that
794 completely opaque pixels are gamma encoded according to
795 the screen_gamma value. Pixels with alpha less than 1.0
796 will still have linear components.
798 Use this format if you have control over your
799 compositing software and so don't do other arithmetic
800 (such as scaling) on the data you get from libpng. Your
801 compositing software can simply copy opaque pixels to
802 the output but still has linear values for the
805 In normal compositing, where the alpha channel encodes
806 partial pixel coverage (as opposed to broad area
807 translucency), the inaccuracies of the 8-bit
808 representation of non-opaque pixels are irrelevant.
810 You can also try this format if your software is broken;
811 it might look better.
813 PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD;
814 however, all component values,
815 including the alpha channel are gamma encoded. This is
816 an appropriate format to try if your software, or more
817 likely hardware, is totally broken, i.e., if it performs
818 linear arithmetic directly on gamma encoded values.
820 In most cases of broken software or hardware the bug in the final display
821 manifests as a subtle halo around composited parts of the image. You may not
822 even perceive this as a halo; the composited part of the image may simply appear
823 separate from the background, as though it had been cut out of paper and pasted
826 If you don't have to deal with bugs in software or hardware, or if you can fix
827 them, there are three recommended ways of using png_set_alpha_mode():
829 png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG,
832 You can do color correction on the result (libpng does not currently
833 support color correction internally). When you handle the alpha channel
834 you need to undo the gamma encoding and multiply out the alpha.
836 png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD,
838 png_set_expand_16(png_ptr);
840 If you are using the high level interface, don't call png_set_expand_16();
841 instead pass PNG_TRANSFORM_EXPAND_16 to the interface.
843 With this mode you can't do color correction, but you can do arithmetic,
844 including composition and scaling, on the data without further processing.
846 png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED,
849 You can avoid the expansion to 16-bit components with this mode, but you
850 lose the ability to scale the image or perform other linear arithmetic.
851 All you can do is compose the result onto a matching output. Since this
852 mode is libpng-specific you also need to write your own composition
855 If you don't need, or can't handle, the alpha channel you can call
856 png_set_background() to remove it by compositing against a fixed color. Don't
857 call png_set_strip_alpha() to do this - it will leave spurious pixel values in
858 transparent parts of this image.
860 png_set_background(png_ptr, &background_color,
861 PNG_BACKGROUND_GAMMA_SCREEN, 0, 1);
863 The background_color is an RGB or grayscale value according to the data format
864 libpng will produce for you. Because you don't yet know the format of the PNG
865 file, if you call png_set_background at this point you must arrange for the
866 format produced by libpng to always have 8-bit or 16-bit components and then
867 store the color as an 8-bit or 16-bit color as appropriate. The color contains
868 separate gray and RGB component values, so you can let libpng produce gray or
869 RGB output according to the input format, but low bit depth grayscale images
870 must always be converted to at least 8-bit format. (Even though low bit depth
871 grayscale images can't have an alpha channel they can have a transparent
874 You set the transforms you need later, either as flags to the high level
875 interface or libpng API calls for the low level interface. For reference the
876 settings and API calls required are:
879 PNG_TRANSFORM_SCALE_16 | PNG_EXPAND
880 png_set_expand(png_ptr); png_set_scale_16(png_ptr);
882 If you must get exactly the same inaccurate results
883 produced by default in versions prior to libpng-1.5.4,
884 use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr)
888 PNG_TRANSFORM_EXPAND_16
889 png_set_expand_16(png_ptr);
891 In either case palette image data will be expanded to RGB. If you just want
892 color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr)
895 Calling png_set_background before the PNG file header is read will not work
896 prior to libpng-1.5.4. Because the failure may result in unexpected warnings or
897 errors it is therefore much safer to call png_set_background after the head has
898 been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be
899 used with the high level interface.
901 The high-level read interface
903 At this point there are two ways to proceed; through the high-level
904 read interface, or through a sequence of low-level read operations.
905 You can use the high-level interface if (a) you are willing to read
906 the entire image into memory, and (b) the input transformations
907 you want to do are limited to the following set:
909 PNG_TRANSFORM_IDENTITY No transformation
910 PNG_TRANSFORM_SCALE_16 Strip 16-bit samples to
912 PNG_TRANSFORM_STRIP_16 Chop 16-bit samples to
913 8-bit less accurately
914 PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel
915 PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit
917 PNG_TRANSFORM_PACKSWAP Change order of packed
919 PNG_TRANSFORM_EXPAND Perform set_expand()
920 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
921 PNG_TRANSFORM_SHIFT Normalize pixels to the
923 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
925 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
927 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
929 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
930 PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples
931 to RGB (or GA to RGBA)
932 PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits
934 (This excludes setting a background color, doing gamma transformation,
935 quantizing, and setting filler.) If this is the case, simply do this:
937 png_read_png(png_ptr, info_ptr, png_transforms, NULL)
939 where png_transforms is an integer containing the bitwise OR of some
940 set of transformation flags. This call is equivalent to png_read_info(),
941 followed the set of transformations indicated by the transform mask,
942 then png_read_image(), and finally png_read_end().
944 (The final parameter of this call is not yet used. Someday it might point
945 to transformation parameters required by some future input transform.)
947 You must use png_transforms and not call any png_set_transform() functions
948 when you use png_read_png().
950 After you have called png_read_png(), you can retrieve the image data
953 row_pointers = png_get_rows(png_ptr, info_ptr);
955 where row_pointers is an array of pointers to the pixel data for each row:
957 png_bytep row_pointers[height];
959 If you know your image size and pixel size ahead of time, you can allocate
960 row_pointers prior to calling png_read_png() with
962 if (height > PNG_UINT_32_MAX/png_sizeof(png_byte))
964 "Image is too tall to process in memory");
966 if (width > PNG_UINT_32_MAX/pixel_size)
968 "Image is too wide to process in memory");
970 row_pointers = png_malloc(png_ptr,
971 height*png_sizeof(png_bytep));
973 for (int i=0; i<height, i++)
974 row_pointers[i]=NULL; /* security precaution */
976 for (int i=0; i<height, i++)
977 row_pointers[i]=png_malloc(png_ptr,
980 png_set_rows(png_ptr, info_ptr, &row_pointers);
982 Alternatively you could allocate your image in one big block and define
983 row_pointers[i] to point into the proper places in your block.
985 If you use png_set_rows(), the application is responsible for freeing
986 row_pointers (and row_pointers[i], if they were separately allocated).
988 If you don't allocate row_pointers ahead of time, png_read_png() will
989 do it, and it'll be free'ed by libpng when you call png_destroy_*().
991 The low-level read interface
993 If you are going the low-level route, you are now ready to read all
994 the file information up to the actual image data. You do this with a
995 call to png_read_info().
997 png_read_info(png_ptr, info_ptr);
999 This will process all chunks up to but not including the image data.
1001 This also copies some of the data from the PNG file into the decode structure
1002 for use in later transformations. Important information copied in is:
1004 1) The PNG file gamma from the gAMA chunk. This overwrites the default value
1005 provided by an earlier call to png_set_gamma or png_set_alpha_mode.
1007 2) Prior to libpng-1.5.4 the background color from a bKGd chunk. This
1008 damages the information provided by an earlier call to png_set_background
1009 resulting in unexpected behavior. Libpng-1.5.4 no longer does this.
1011 3) The number of significant bits in each component value. Libpng uses this to
1012 optimize gamma handling by reducing the internal lookup table sizes.
1014 4) The transparent color information from a tRNS chunk. This can be modified by
1015 a later call to png_set_tRNS.
1017 Querying the info structure
1019 Functions are used to get the information from the info_ptr once it
1020 has been read. Note that these fields may not be completely filled
1021 in until png_read_end() has read the chunk data following the image.
1023 png_get_IHDR(png_ptr, info_ptr, &width, &height,
1024 &bit_depth, &color_type, &interlace_type,
1025 &compression_type, &filter_method);
1027 width - holds the width of the image
1028 in pixels (up to 2^31).
1030 height - holds the height of the image
1031 in pixels (up to 2^31).
1033 bit_depth - holds the bit depth of one of the
1034 image channels. (valid values are
1035 1, 2, 4, 8, 16 and depend also on
1036 the color_type. See also
1037 significant bits (sBIT) below).
1039 color_type - describes which color/alpha channels
1042 (bit depths 1, 2, 4, 8, 16)
1043 PNG_COLOR_TYPE_GRAY_ALPHA
1045 PNG_COLOR_TYPE_PALETTE
1046 (bit depths 1, 2, 4, 8)
1049 PNG_COLOR_TYPE_RGB_ALPHA
1052 PNG_COLOR_MASK_PALETTE
1053 PNG_COLOR_MASK_COLOR
1054 PNG_COLOR_MASK_ALPHA
1056 interlace_type - (PNG_INTERLACE_NONE or
1057 PNG_INTERLACE_ADAM7)
1059 compression_type - (must be PNG_COMPRESSION_TYPE_BASE
1062 filter_method - (must be PNG_FILTER_TYPE_BASE
1063 for PNG 1.0, and can also be
1064 PNG_INTRAPIXEL_DIFFERENCING if
1065 the PNG datastream is embedded in
1066 a MNG-1.0 datastream)
1068 Any or all of interlace_type, compression_type, or
1069 filter_method can be NULL if you are
1070 not interested in their values.
1072 Note that png_get_IHDR() returns 32-bit data into
1073 the application's width and height variables.
1074 This is an unsafe situation if these are 16-bit
1075 variables. In such situations, the
1076 png_get_image_width() and png_get_image_height()
1077 functions described below are safer.
1079 width = png_get_image_width(png_ptr,
1082 height = png_get_image_height(png_ptr,
1085 bit_depth = png_get_bit_depth(png_ptr,
1088 color_type = png_get_color_type(png_ptr,
1091 interlace_type = png_get_interlace_type(png_ptr,
1094 compression_type = png_get_compression_type(png_ptr,
1097 filter_method = png_get_filter_type(png_ptr,
1100 channels = png_get_channels(png_ptr, info_ptr);
1102 channels - number of channels of info for the
1103 color type (valid values are 1 (GRAY,
1104 PALETTE), 2 (GRAY_ALPHA), 3 (RGB),
1105 4 (RGB_ALPHA or RGB + filler byte))
1107 rowbytes = png_get_rowbytes(png_ptr, info_ptr);
1109 rowbytes - number of bytes needed to hold a row
1111 signature = png_get_signature(png_ptr, info_ptr);
1113 signature - holds the signature read from the
1114 file (if any). The data is kept in
1115 the same offset it would be if the
1116 whole signature were read (i.e. if an
1117 application had already read in 4
1118 bytes of signature before starting
1119 libpng, the remaining 4 bytes would
1120 be in signature[4] through signature[7]
1121 (see png_set_sig_bytes())).
1123 These are also important, but their validity depends on whether the chunk
1124 has been read. The png_get_valid(png_ptr, info_ptr, PNG_INFO_<chunk>) and
1125 png_get_<chunk>(png_ptr, info_ptr, ...) functions return non-zero if the
1126 data has been read, or zero if it is missing. The parameters to the
1127 png_get_<chunk> are set directly if they are simple data types, or a
1128 pointer into the info_ptr is returned for any complex types.
1130 The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks
1131 is simply returned to give the application information about how the
1132 image was encoded. Libpng itself only does transformations using the file
1133 gamma when combining semitransparent pixels with the background color.
1135 png_get_PLTE(png_ptr, info_ptr, &palette,
1138 palette - the palette for the file
1139 (array of png_color)
1141 num_palette - number of entries in the palette
1143 png_get_gAMA(png_ptr, info_ptr, &file_gamma);
1144 png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma);
1146 file_gamma - the gamma at which the file was
1147 written (PNG_INFO_gAMA)
1149 int_file_gamma - 100,000 times the gamma at which the
1152 png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x,
1153 &red_y, &green_x, &green_y, &blue_x, &blue_y)
1154 png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, &green_X,
1155 &green_Y, &green_Z, &blue_X, &blue_Y, &blue_Z)
1156 png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, &int_white_y,
1157 &int_red_x, &int_red_y, &int_green_x, &int_green_y,
1158 &int_blue_x, &int_blue_y)
1159 png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y,
1160 &int_red_Z, &int_green_X, &int_green_Y, &int_green_Z,
1161 &int_blue_X, &int_blue_Y, &int_blue_Z)
1163 {white,red,green,blue}_{x,y}
1164 A color space encoding specified using the
1165 chromaticities of the end points and the
1166 white point. (PNG_INFO_cHRM)
1168 {red,green,blue}_{X,Y,Z}
1169 A color space encoding specified using the encoding end
1170 points - the CIE tristimulus specification of the intended
1171 color of the red, green and blue channels in the PNG RGB
1172 data. The white point is simply the sum of the three end
1173 points. (PNG_INFO_cHRM)
1175 png_get_sRGB(png_ptr, info_ptr, &srgb_intent);
1177 file_srgb_intent - the rendering intent (PNG_INFO_sRGB)
1178 The presence of the sRGB chunk
1179 means that the pixel data is in the
1180 sRGB color space. This chunk also
1181 implies specific values of gAMA and
1184 png_get_iCCP(png_ptr, info_ptr, &name,
1185 &compression_type, &profile, &proflen);
1187 name - The profile name.
1189 compression_type - The compression type; always
1190 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
1191 You may give NULL to this argument to
1194 profile - International Color Consortium color
1195 profile data. May contain NULs.
1197 proflen - length of profile data in bytes.
1199 png_get_sBIT(png_ptr, info_ptr, &sig_bit);
1201 sig_bit - the number of significant bits for
1202 (PNG_INFO_sBIT) each of the gray,
1203 red, green, and blue channels,
1204 whichever are appropriate for the
1205 given color type (png_color_16)
1207 png_get_tRNS(png_ptr, info_ptr, &trans_alpha,
1208 &num_trans, &trans_color);
1210 trans_alpha - array of alpha (transparency)
1211 entries for palette (PNG_INFO_tRNS)
1213 num_trans - number of transparent entries
1216 trans_color - graylevel or color sample values of
1217 the single transparent color for
1218 non-paletted images (PNG_INFO_tRNS)
1220 png_get_hIST(png_ptr, info_ptr, &hist);
1223 hist - histogram of palette (array of
1226 png_get_tIME(png_ptr, info_ptr, &mod_time);
1228 mod_time - time image was last modified
1231 png_get_bKGD(png_ptr, info_ptr, &background);
1233 background - background color (of type
1234 png_color_16p) (PNG_VALID_bKGD)
1235 valid 16-bit red, green and blue
1236 values, regardless of color_type
1238 num_comments = png_get_text(png_ptr, info_ptr,
1239 &text_ptr, &num_text);
1241 num_comments - number of comments
1243 text_ptr - array of png_text holding image
1246 text_ptr[i].compression - type of compression used
1247 on "text" PNG_TEXT_COMPRESSION_NONE
1248 PNG_TEXT_COMPRESSION_zTXt
1249 PNG_ITXT_COMPRESSION_NONE
1250 PNG_ITXT_COMPRESSION_zTXt
1252 text_ptr[i].key - keyword for comment. Must contain
1255 text_ptr[i].text - text comments for current
1256 keyword. Can be empty.
1258 text_ptr[i].text_length - length of text string,
1259 after decompression, 0 for iTXt
1261 text_ptr[i].itxt_length - length of itxt string,
1262 after decompression, 0 for tEXt/zTXt
1264 text_ptr[i].lang - language of comment (empty
1265 string for unknown).
1267 text_ptr[i].lang_key - keyword in UTF-8
1268 (empty string for unknown).
1270 Note that the itxt_length, lang, and lang_key
1271 members of the text_ptr structure only exist when the
1272 library is built with iTXt chunk support. Prior to
1273 libpng-1.4.0 the library was built by default without
1274 iTXt support. Also note that when iTXt is supported,
1275 they contain NULL pointers when the "compression"
1276 field contains PNG_TEXT_COMPRESSION_NONE or
1277 PNG_TEXT_COMPRESSION_zTXt.
1279 num_text - number of comments (same as
1280 num_comments; you can put NULL here
1281 to avoid the duplication)
1283 Note while png_set_text() will accept text, language,
1284 and translated keywords that can be NULL pointers, the
1285 structure returned by png_get_text will always contain
1286 regular zero-terminated C strings. They might be
1287 empty strings but they will never be NULL pointers.
1289 num_spalettes = png_get_sPLT(png_ptr, info_ptr,
1292 num_spalettes - number of sPLT chunks read.
1294 palette_ptr - array of palette structures holding
1295 contents of one or more sPLT chunks
1298 png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y,
1301 offset_x - positive offset from the left edge
1302 of the screen (can be negative)
1304 offset_y - positive offset from the top edge
1305 of the screen (can be negative)
1307 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
1309 png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y,
1312 res_x - pixels/unit physical resolution in
1315 res_y - pixels/unit physical resolution in
1318 unit_type - PNG_RESOLUTION_UNKNOWN,
1319 PNG_RESOLUTION_METER
1321 png_get_sCAL(png_ptr, info_ptr, &unit, &width,
1324 unit - physical scale units (an integer)
1326 width - width of a pixel in physical scale units
1328 height - height of a pixel in physical scale units
1329 (width and height are doubles)
1331 png_get_sCAL_s(png_ptr, info_ptr, &unit, &width,
1334 unit - physical scale units (an integer)
1336 width - width of a pixel in physical scale units
1337 (expressed as a string)
1339 height - height of a pixel in physical scale units
1340 (width and height are strings like "2.54")
1342 num_unknown_chunks = png_get_unknown_chunks(png_ptr,
1343 info_ptr, &unknowns)
1345 unknowns - array of png_unknown_chunk
1346 structures holding unknown chunks
1348 unknowns[i].name - name of unknown chunk
1350 unknowns[i].data - data of unknown chunk
1352 unknowns[i].size - size of unknown chunk's data
1354 unknowns[i].location - position of chunk in file
1356 The value of "i" corresponds to the order in which the
1357 chunks were read from the PNG file or inserted with the
1358 png_set_unknown_chunks() function.
1360 The value of "location" is a bitwise "or" of
1362 PNG_HAVE_IHDR (0x01)
1363 PNG_HAVE_PLTE (0x02)
1364 PNG_AFTER_IDAT (0x08)
1366 The data from the pHYs chunk can be retrieved in several convenient
1369 res_x = png_get_x_pixels_per_meter(png_ptr,
1372 res_y = png_get_y_pixels_per_meter(png_ptr,
1375 res_x_and_y = png_get_pixels_per_meter(png_ptr,
1378 res_x = png_get_x_pixels_per_inch(png_ptr,
1381 res_y = png_get_y_pixels_per_inch(png_ptr,
1384 res_x_and_y = png_get_pixels_per_inch(png_ptr,
1387 aspect_ratio = png_get_pixel_aspect_ratio(png_ptr,
1390 Each of these returns 0 [signifying "unknown"] if
1391 the data is not present or if res_x is 0;
1392 res_x_and_y is 0 if res_x != res_y
1394 Note that because of the way the resolutions are
1395 stored internally, the inch conversions won't
1396 come out to exactly even number. For example,
1397 72 dpi is stored as 0.28346 pixels/meter, and
1398 when this is retrieved it is 71.9988 dpi, so
1399 be sure to round the returned value appropriately
1400 if you want to display a reasonable-looking result.
1402 The data from the oFFs chunk can be retrieved in several convenient
1405 x_offset = png_get_x_offset_microns(png_ptr, info_ptr);
1407 y_offset = png_get_y_offset_microns(png_ptr, info_ptr);
1409 x_offset = png_get_x_offset_inches(png_ptr, info_ptr);
1411 y_offset = png_get_y_offset_inches(png_ptr, info_ptr);
1413 Each of these returns 0 [signifying "unknown" if both
1414 x and y are 0] if the data is not present or if the
1415 chunk is present but the unit is the pixel. The
1416 remark about inexact inch conversions applies here
1417 as well, because a value in inches can't always be
1418 converted to microns and back without some loss
1421 For more information, see the
1422 PNG specification for chunk contents. Be careful with trusting
1423 rowbytes, as some of the transformations could increase the space
1424 needed to hold a row (expand, filler, gray_to_rgb, etc.).
1425 See png_read_update_info(), below.
1427 A quick word about text_ptr and num_text. PNG stores comments in
1428 keyword/text pairs, one pair per chunk, with no limit on the number
1429 of text chunks, and a 2^31 byte limit on their size. While there are
1430 suggested keywords, there is no requirement to restrict the use to these
1431 strings. It is strongly suggested that keywords and text be sensible
1432 to humans (that's the point), so don't use abbreviations. Non-printing
1433 symbols are not allowed. See the PNG specification for more details.
1434 There is also no requirement to have text after the keyword.
1436 Keywords should be limited to 79 Latin-1 characters without leading or
1437 trailing spaces, but non-consecutive spaces are allowed within the
1438 keyword. It is possible to have the same keyword any number of times.
1439 The text_ptr is an array of png_text structures, each holding a
1440 pointer to a language string, a pointer to a keyword and a pointer to
1441 a text string. The text string, language code, and translated
1442 keyword may be empty or NULL pointers. The keyword/text
1443 pairs are put into the array in the order that they are received.
1444 However, some or all of the text chunks may be after the image, so, to
1445 make sure you have read all the text chunks, don't mess with these
1446 until after you read the stuff after the image. This will be
1447 mentioned again below in the discussion that goes with png_read_end().
1449 Input transformations
1451 After you've read the header information, you can set up the library
1452 to handle any special transformations of the image data. The various
1453 ways to transform the data will be described in the order that they
1454 should occur. This is important, as some of these change the color
1455 type and/or bit depth of the data, and some others only work on
1456 certain color types and bit depths.
1458 Transformations you request are ignored if they don't have any meaning for a
1459 particular input data format. However some transformations can have an effect
1460 as a result of a previous transformation. If you specify a contradictory set of
1461 transformations, for example both adding and removing the alpha channel, you
1462 cannot predict the final result.
1464 The color used for the transparency values should be supplied in the same
1465 format/depth as the current image data. It is stored in the same format/depth
1466 as the image data in a tRNS chunk, so this is what libpng expects for this data.
1468 The color used for the background value depends on the need_expand argument as
1471 Data will be decoded into the supplied row buffers packed into bytes
1472 unless the library has been told to transform it into another format.
1473 For example, 4 bit/pixel paletted or grayscale data will be returned
1474 2 pixels/byte with the leftmost pixel in the high-order bits of the
1475 byte, unless png_set_packing() is called. 8-bit RGB data will be stored
1476 in RGB RGB RGB format unless png_set_filler() or png_set_add_alpha()
1477 is called to insert filler bytes, either before or after each RGB triplet.
1478 16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant
1479 byte of the color value first, unless png_set_scale_16() is called to
1480 transform it to regular RGB RGB triplets, or png_set_filler() or
1481 png_set_add alpha() is called to insert filler bytes, either before or
1482 after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can
1483 be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(),
1484 or png_set_scale_16().
1486 The following code transforms grayscale images of less than 8 to 8 bits,
1487 changes paletted images to RGB, and adds a full alpha channel if there is
1488 transparency information in a tRNS chunk. This is most useful on
1489 grayscale images with bit depths of 2 or 4 or if there is a multiple-image
1490 viewing application that wishes to treat all images in the same way.
1492 if (color_type == PNG_COLOR_TYPE_PALETTE)
1493 png_set_palette_to_rgb(png_ptr);
1495 if (png_get_valid(png_ptr, info_ptr,
1496 PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr);
1498 if (color_type == PNG_COLOR_TYPE_GRAY &&
1499 bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr);
1501 The first two functions are actually aliases for png_set_expand(), added
1502 in libpng version 1.0.4, with the function names expanded to improve code
1503 readability. In some future version they may actually do different
1506 As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
1507 added. It expands the sample depth without changing tRNS to alpha.
1509 As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as
1510 png_set_expand(); however, the resultant channels have 16 bits rather than 8.
1511 Use this when the output color or gray channels are made linear to avoid fairly
1512 severe accuracy loss.
1515 png_set_expand_16(png_ptr);
1517 PNG can have files with 16 bits per channel. If you only can handle
1518 8 bits per channel, this will strip the pixels down to 8-bit.
1520 if (bit_depth == 16)
1521 #if PNG_LIBPNG_VER >= 10504
1522 png_set_scale_16(png_ptr);
1524 png_set_strip_16(png_ptr);
1527 (The more accurate "png_set_scale_16()" API became available in libpng version
1530 If you need to process the alpha channel on the image separately from the image
1531 data (for example if you convert it to a bitmap mask) it is possible to have
1532 libpng strip the channel leaving just RGB or gray data:
1534 if (color_type & PNG_COLOR_MASK_ALPHA)
1535 png_set_strip_alpha(png_ptr);
1537 If you strip the alpha channel you need to find some other way of dealing with
1538 the information. If, instead, you want to convert the image to an opaque
1539 version with no alpha channel use png_set_background; see below.
1541 As of libpng version 1.5.2, almost all useful expansions are supported, the
1542 major ommissions are conversion of grayscale to indexed images (which can be
1543 done trivially in the application) and conversion of indexed to grayscale (which
1544 can be done by a trivial manipulation of the palette.)
1546 In the following table, the 01 means grayscale with depth<8, 31 means
1547 indexed with depth<8, other numerals represent the color type, "T" means
1548 the tRNS chunk is present, A means an alpha channel is present, and O
1549 means tRNS or alpha is present but all pixels in the image are opaque.
1551 FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O
1553 01 - [G] - - - - - - - - - - - - -
1554 31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q
1555 0 1 G + . . G G G G G G B B GB GB
1556 0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt
1557 0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt
1558 2 C P C C C + . . C - - CB CB B B
1559 2T Ct - Ct C C t + t - - - CBt CBt Bt Bt
1560 2O Ct - Ct C C t t + - - - CBt CBt Bt Bt
1561 3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q
1562 3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt
1563 3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt
1564 4A lA G A T T GA GT GT GA GT GT + BA G GBA
1565 4O lA GBA A T T GA GT GT GA GT GT BA + GBA G
1566 6A CA PA CA C C A T tT PA P P C CBA + BA
1567 6O CA PBA CA C C A tT T PA P P CBA C BA +
1570 "+" identifies entries where 'from' and 'to' are the same.
1571 "-" means the transformation is not supported.
1572 "." means nothing is necessary (a tRNS chunk can just be ignored).
1573 "t" means the transformation is obtained by png_set_tRNS.
1574 "A" means the transformation is obtained by png_set_add_alpha().
1575 "X" means the transformation is obtained by png_set_expand().
1576 "1" means the transformation is obtained by
1577 png_set_expand_gray_1_2_4_to_8() (and by png_set_expand()
1578 if there is no transparency in the original or the final
1580 "C" means the transformation is obtained by png_set_gray_to_rgb().
1581 "G" means the transformation is obtained by png_set_rgb_to_gray().
1582 "P" means the transformation is obtained by
1583 png_set_expand_palette_to_rgb().
1584 "p" means the transformation is obtained by png_set_packing().
1585 "Q" means the transformation is obtained by png_set_quantize().
1586 "T" means the transformation is obtained by
1587 png_set_tRNS_to_alpha().
1588 "B" means the transformation is obtained by
1589 png_set_background(), or png_strip_alpha().
1591 When an entry has multiple transforms listed all are required to cause the
1592 right overall transformation. When two transforms are separated by a comma
1593 either will do the job. When transforms are enclosed in [] the transform should
1594 do the job but this is currently unimplemented - a different format will result
1595 if the suggested transformations are used.
1597 In PNG files, the alpha channel in an image
1598 is the level of opacity. If you need the alpha channel in an image to
1599 be the level of transparency instead of opacity, you can invert the
1600 alpha channel (or the tRNS chunk data) after it's read, so that 0 is
1601 fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit
1602 images) is fully transparent, with
1604 png_set_invert_alpha(png_ptr);
1606 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
1607 they can, resulting in, for example, 8 pixels per byte for 1 bit
1608 files. This code expands to 1 pixel per byte without changing the
1609 values of the pixels:
1612 png_set_packing(png_ptr);
1614 PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels
1615 stored in a PNG image have been "scaled" or "shifted" up to the next
1616 higher possible bit depth (e.g. from 5 bits/sample in the range [0,31]
1617 to 8 bits/sample in the range [0, 255]). However, it is also possible
1618 to convert the PNG pixel data back to the original bit depth of the
1619 image. This call reduces the pixels back down to the original bit depth:
1621 png_color_8p sig_bit;
1623 if (png_get_sBIT(png_ptr, info_ptr, &sig_bit))
1624 png_set_shift(png_ptr, sig_bit);
1626 PNG files store 3-color pixels in red, green, blue order. This code
1627 changes the storage of the pixels to blue, green, red:
1629 if (color_type == PNG_COLOR_TYPE_RGB ||
1630 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1631 png_set_bgr(png_ptr);
1633 PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them
1634 into 4 or 8 bytes for windowing systems that need them in this format:
1636 if (color_type == PNG_COLOR_TYPE_RGB)
1637 png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE);
1639 where "filler" is the 8 or 16-bit number to fill with, and the location is
1640 either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether
1641 you want the filler before the RGB or after. This transformation
1642 does not affect images that already have full alpha channels. To add an
1643 opaque alpha channel, use filler=0xff or 0xffff and PNG_FILLER_AFTER which
1644 will generate RGBA pixels.
1646 Note that png_set_filler() does not change the color type. If you want
1647 to do that, you can add a true alpha channel with
1649 if (color_type == PNG_COLOR_TYPE_RGB ||
1650 color_type == PNG_COLOR_TYPE_GRAY)
1651 png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER);
1653 where "filler" contains the alpha value to assign to each pixel.
1654 This function was added in libpng-1.2.7.
1656 If you are reading an image with an alpha channel, and you need the
1657 data as ARGB instead of the normal PNG format RGBA:
1659 if (color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1660 png_set_swap_alpha(png_ptr);
1662 For some uses, you may want a grayscale image to be represented as
1663 RGB. This code will do that conversion:
1665 if (color_type == PNG_COLOR_TYPE_GRAY ||
1666 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1667 png_set_gray_to_rgb(png_ptr);
1669 Conversely, you can convert an RGB or RGBA image to grayscale or grayscale
1672 if (color_type == PNG_COLOR_TYPE_RGB ||
1673 color_type == PNG_COLOR_TYPE_RGB_ALPHA)
1674 png_set_rgb_to_gray(png_ptr, error_action,
1675 double red_weight, double green_weight);
1677 error_action = 1: silently do the conversion
1679 error_action = 2: issue a warning if the original
1680 image has any pixel where
1681 red != green or red != blue
1683 error_action = 3: issue an error and abort the
1684 conversion if the original
1685 image has any pixel where
1686 red != green or red != blue
1688 red_weight: weight of red component
1690 green_weight: weight of green component
1691 If either weight is negative, default
1694 In the corresponding fixed point API the red_weight and green_weight values are
1695 simply scaled by 100,000:
1697 png_set_rgb_to_gray(png_ptr, error_action,
1698 png_fixed_point red_weight,
1699 png_fixed_point green_weight);
1701 If you have set error_action = 1 or 2, you can
1702 later check whether the image really was gray, after processing
1703 the image rows, with the png_get_rgb_to_gray_status(png_ptr) function.
1704 It will return a png_byte that is zero if the image was gray or
1705 1 if there were any non-gray pixels. Background and sBIT data
1706 will be silently converted to grayscale, using the green channel
1707 data for sBIT, regardless of the error_action setting.
1709 The default values come from the PNG file cHRM chunk if present; otherwise, the
1710 defaults correspond to the ITU-R recommendation 709, and also the sRGB color
1711 space, as recommended in the Charles Poynton's Colour FAQ,
1712 <http://www.poynton.com/>, in section 9:
1714 <http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html#RTFToC9>
1716 Y = 0.2126 * R + 0.7152 * G + 0.0722 * B
1718 Previous versions of this document, 1998 through 2002, recommended a slightly
1721 Y = 0.212671 * R + 0.715160 * G + 0.072169 * B
1723 Libpng uses an integer approximation:
1725 Y = (6968 * R + 23434 * G + 2366 * B)/32768
1727 The calculation is done in a linear colorspace, if the image gamma
1730 The png_set_background() function has been described already; it tells libpng to
1731 composite images with alpha or simple transparency against the supplied
1732 background color. For compatibility with versions of libpng earlier than
1733 libpng-1.5.4 it is recommended that you call the function after reading the file
1734 header, even if you don't want to use the color in a bKGD chunk, if one exists.
1736 If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid),
1737 you may use this color, or supply another color more suitable for
1738 the current display (e.g., the background color from a web page). You
1739 need to tell libpng how the color is represented, both the format of the
1740 component values in the color (the number of bits) and the gamma encoding of the
1741 color. The function takes two arguments, background_gamma_mode and need_expand
1742 to convey this information; however, only two combinations are likely to be
1745 png_color_16 my_background;
1746 png_color_16p image_background;
1748 if (png_get_bKGD(png_ptr, info_ptr, &image_background))
1749 png_set_background(png_ptr, image_background,
1750 PNG_BACKGROUND_GAMMA_FILE, 1/*needs to be expanded*/, 1);
1752 png_set_background(png_ptr, &my_background,
1753 PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1);
1755 The second call was described above - my_background is in the format of the
1756 final, display, output produced by libpng. Because you now know the format of
1757 the PNG it is possible to avoid the need to choose either 8-bit or 16-bit
1758 output and to retain palette images (the palette colors will be modified
1759 appropriately and the tRNS chunk removed.) However, if you are doing this,
1760 take great care not to ask for transformations without checking first that
1763 In the first call the background color has the original bit depth and color type
1764 of the PNG file. So, for palette images the color is supplied as a palette
1765 index and for low bit greyscale images the color is a reduced bit value in
1766 image_background->gray.
1768 If you didn't call png_set_gamma() before reading the file header, for example
1769 if you need your code to remain compatible with older versions of libpng prior
1770 to libpng-1.5.4, this is the place to call it.
1772 Do not call it if you called png_set_alpha_mode(); doing so will damage the
1773 settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is
1774 supported then you can certainly do png_set_gamma() before reading the PNG
1777 This API unconditionally sets the screen and file gamma values, so it will
1778 override the value in the PNG file unless it is called before the PNG file
1779 reading starts. For this reason you must always call it with the PNG file
1780 value when you call it in this position:
1782 if (png_get_gAMA(png_ptr, info_ptr, &file_gamma))
1783 png_set_gamma(png_ptr, screen_gamma, file_gamma);
1786 png_set_gamma(png_ptr, screen_gamma, 0.45455);
1788 If you need to reduce an RGB file to a paletted file, or if a paletted
1789 file has more entries then will fit on your screen, png_set_quantize()
1790 will do that. Note that this is a simple match quantization that merely
1791 finds the closest color available. This should work fairly well with
1792 optimized palettes, but fairly badly with linear color cubes. If you
1793 pass a palette that is larger than maximum_colors, the file will
1794 reduce the number of colors in the palette so it will fit into
1795 maximum_colors. If there is a histogram, libpng will use it to make
1796 more intelligent choices when reducing the palette. If there is no
1797 histogram, it may not do as good a job.
1799 if (color_type & PNG_COLOR_MASK_COLOR)
1801 if (png_get_valid(png_ptr, info_ptr,
1804 png_uint_16p histogram = NULL;
1806 png_get_hIST(png_ptr, info_ptr,
1808 png_set_quantize(png_ptr, palette, num_palette,
1809 max_screen_colors, histogram, 1);
1814 png_color std_color_cube[MAX_SCREEN_COLORS] =
1817 png_set_quantize(png_ptr, std_color_cube,
1818 MAX_SCREEN_COLORS, MAX_SCREEN_COLORS,
1823 PNG files describe monochrome as black being zero and white being one.
1824 The following code will reverse this (make black be one and white be
1827 if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY)
1828 png_set_invert_mono(png_ptr);
1830 This function can also be used to invert grayscale and gray-alpha images:
1832 if (color_type == PNG_COLOR_TYPE_GRAY ||
1833 color_type == PNG_COLOR_TYPE_GRAY_ALPHA)
1834 png_set_invert_mono(png_ptr);
1836 PNG files store 16-bit pixels in network byte order (big-endian,
1837 ie. most significant bits first). This code changes the storage to the
1838 other way (little-endian, i.e. least significant bits first, the
1839 way PCs store them):
1841 if (bit_depth == 16)
1842 png_set_swap(png_ptr);
1844 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
1845 need to change the order the pixels are packed into bytes, you can use:
1848 png_set_packswap(png_ptr);
1850 Finally, you can write your own transformation function if none of
1851 the existing ones meets your needs. This is done by setting a callback
1854 png_set_read_user_transform_fn(png_ptr,
1857 You must supply the function
1859 void read_transform_fn(png_structp png_ptr, png_row_infop
1860 row_info, png_bytep data)
1862 See pngtest.c for a working example. Your function will be called
1863 after all of the other transformations have been processed. Take care with
1864 interlaced images if you do the interlace yourself - the width of the row is the
1865 width in 'row_info', not the overall image width.
1867 If supported, libpng provides two information routines that you can use to find
1868 where you are in processing the image:
1870 png_get_current_pass_number(png_structp png_ptr);
1871 png_get_current_row_number(png_structp png_ptr);
1873 Don't try using these outside a transform callback - firstly they are only
1874 supported if user transforms are supported, secondly they may well return
1875 unexpected results unless the row is actually being processed at the moment they
1879 images the value returned is the row in the input sub-image image. Use
1880 PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
1881 find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
1883 The discussion of interlace handling above contains more information on how to
1886 You can also set up a pointer to a user structure for use by your
1887 callback function, and you can inform libpng that your transform
1888 function will change the number of channels or bit depth with the
1891 png_set_user_transform_info(png_ptr, user_ptr,
1892 user_depth, user_channels);
1894 The user's application, not libpng, is responsible for allocating and
1895 freeing any memory required for the user structure.
1897 You can retrieve the pointer via the function
1898 png_get_user_transform_ptr(). For example:
1900 voidp read_user_transform_ptr =
1901 png_get_user_transform_ptr(png_ptr);
1903 The last thing to handle is interlacing; this is covered in detail below,
1904 but you must call the function here if you want libpng to handle expansion
1905 of the interlaced image.
1907 number_of_passes = png_set_interlace_handling(png_ptr);
1909 After setting the transformations, libpng can update your png_info
1910 structure to reflect any transformations you've requested with this
1913 png_read_update_info(png_ptr, info_ptr);
1915 This is most useful to update the info structure's rowbytes
1916 field so you can use it to allocate your image memory. This function
1917 will also update your palette with the correct screen_gamma and
1918 background if these have been given with the calls above. You may
1919 only call png_read_update_info() once with a particular info_ptr.
1921 After you call png_read_update_info(), you can allocate any
1922 memory you need to hold the image. The row data is simply
1923 raw byte data for all forms of images. As the actual allocation
1924 varies among applications, no example will be given. If you
1925 are allocating one large chunk, you will need to build an
1926 array of pointers to each row, as it will be needed for some
1927 of the functions below.
1929 Remember: Before you call png_read_update_info(), the png_get_*()
1930 functions return the values corresponding to the original PNG image.
1931 After you call png_read_update_info the values refer to the image
1932 that libpng will output. Consequently you must call all the png_set_
1933 functions before you call png_read_update_info(). This is particularly
1934 important for png_set_interlace_handling() - if you are going to call
1935 png_read_update_info() you must call png_set_interlace_handling() before
1936 it unless you want to receive interlaced output.
1940 After you've allocated memory, you can read the image data.
1941 The simplest way to do this is in one function call. If you are
1942 allocating enough memory to hold the whole image, you can just
1943 call png_read_image() and libpng will read in all the image data
1944 and put it in the memory area supplied. You will need to pass in
1945 an array of pointers to each row.
1947 This function automatically handles interlacing, so you don't
1948 need to call png_set_interlace_handling() (unless you call
1949 png_read_update_info()) or call this function multiple times, or any
1950 of that other stuff necessary with png_read_rows().
1952 png_read_image(png_ptr, row_pointers);
1954 where row_pointers is:
1956 png_bytep row_pointers[height];
1958 You can point to void or char or whatever you use for pixels.
1960 If you don't want to read in the whole image at once, you can
1961 use png_read_rows() instead. If there is no interlacing (check
1962 interlace_type == PNG_INTERLACE_NONE), this is simple:
1964 png_read_rows(png_ptr, row_pointers, NULL,
1967 where row_pointers is the same as in the png_read_image() call.
1969 If you are doing this just one row at a time, you can do this with
1970 a single row_pointer instead of an array of row_pointers:
1972 png_bytep row_pointer = row;
1973 png_read_row(png_ptr, row_pointer, NULL);
1975 If the file is interlaced (interlace_type != 0 in the IHDR chunk), things
1976 get somewhat harder. The only current (PNG Specification version 1.2)
1977 interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7);
1978 a somewhat complicated 2D interlace scheme, known as Adam7, that
1979 breaks down an image into seven smaller images of varying size, based
1980 on an 8x8 grid. This number is defined (from libpng 1.5) as
1981 PNG_INTERLACE_ADAM7_PASSES in png.h
1983 libpng can fill out those images or it can give them to you "as is".
1984 It is almost always better to have libpng handle the interlacing for you.
1985 If you want the images filled out, there are two ways to do that. The one
1986 mentioned in the PNG specification is to expand each pixel to cover
1987 those pixels that have not been read yet (the "rectangle" method).
1988 This results in a blocky image for the first pass, which gradually
1989 smooths out as more pixels are read. The other method is the "sparkle"
1990 method, where pixels are drawn only in their final locations, with the
1991 rest of the image remaining whatever colors they were initialized to
1992 before the start of the read. The first method usually looks better,
1993 but tends to be slower, as there are more pixels to put in the rows.
1995 If, as is likely, you want libpng to expand the images, call this before
1996 calling png_start_read_image() or png_read_update_info():
1998 if (interlace_type == PNG_INTERLACE_ADAM7)
2000 = png_set_interlace_handling(png_ptr);
2002 This will return the number of passes needed. Currently, this is seven,
2003 but may change if another interlace type is added. This function can be
2004 called even if the file is not interlaced, where it will return one pass.
2005 You then need to read the whole image 'number_of_passes' times. Each time
2006 will distribute the pixels from the current pass to the correct place in
2007 the output image, so you need to supply the same rows to png_read_rows in
2010 If you are not going to display the image after each pass, but are
2011 going to wait until the entire image is read in, use the sparkle
2012 effect. This effect is faster and the end result of either method
2013 is exactly the same. If you are planning on displaying the image
2014 after each pass, the "rectangle" effect is generally considered the
2017 If you only want the "sparkle" effect, just call png_read_rows() as
2018 normal, with the third parameter NULL. Make sure you make pass over
2019 the image number_of_passes times, and you don't change the data in the
2020 rows between calls. You can change the locations of the data, just
2021 not the data. Each pass only writes the pixels appropriate for that
2022 pass, and assumes the data from previous passes is still valid.
2024 png_read_rows(png_ptr, row_pointers, NULL,
2027 If you only want the first effect (the rectangles), do the same as
2028 before except pass the row buffer in the third parameter, and leave
2029 the second parameter NULL.
2031 png_read_rows(png_ptr, NULL, row_pointers,
2034 If you don't want libpng to handle the interlacing details, just call
2035 png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images.
2036 Each of the images is a valid image by itself; however, you will almost
2037 certainly need to distribute the pixels from each sub-image to the
2038 correct place. This is where everything gets very tricky.
2040 If you want to retrieve the separate images you must pass the correct
2041 number of rows to each successive call of png_read_rows(). The calculation
2042 gets pretty complicated for small images, where some sub-images may
2043 not even exist because either their width or height ends up zero.
2044 libpng provides two macros to help you in 1.5 and later versions:
2046 png_uint_32 width = PNG_PASS_COLS(image_width, pass_number);
2047 png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number);
2049 Respectively these tell you the width and height of the sub-image
2050 corresponding to the numbered pass. 'pass' is in in the range 0 to 6 -
2051 this can be confusing because the specification refers to the same passes
2052 as 1 to 7! Be careful, you must check both the width and height before
2053 calling png_read_rows() and not call it for that pass if either is zero.
2055 You can, of course, read each sub-image row by row. If you want to
2056 produce optimal code to make a pixel-by-pixel transformation of an
2057 interlaced image this is the best approach; read each row of each pass,
2058 transform it, and write it out to a new interlaced image.
2060 If you want to de-interlace the image yourself libpng provides further
2061 macros to help that tell you where to place the pixels in the output image.
2062 Because the interlacing scheme is rectangular - sub-image pixels are always
2063 arranged on a rectangular grid - all you need to know for each pass is the
2064 starting column and row in the output image of the first pixel plus the
2065 spacing between each pixel. As of libpng 1.5 there are four macros to
2066 retrieve this information:
2068 png_uint_32 x = PNG_PASS_START_COL(pass);
2069 png_uint_32 y = PNG_PASS_START_ROW(pass);
2070 png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass);
2071 png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass);
2073 These allow you to write the obvious loop:
2075 png_uint_32 input_y = 0;
2076 png_uint_32 output_y = PNG_PASS_START_ROW(pass);
2078 while (output_y < output_image_height)
2080 png_uint_32 input_x = 0;
2081 png_uint_32 output_x = PNG_PASS_START_COL(pass);
2083 while (output_x < output_image_width)
2085 image[output_y][output_x] =
2086 subimage[pass][input_y][input_x++];
2095 Notice that the steps between successive output rows and columns are
2096 returned as shifts. This is possible because the pixels in the subimages
2097 are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original
2098 image. In practice you may need to directly calculate the output coordinate
2099 given an input coordinate. libpng provides two further macros for this
2102 png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass);
2103 png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass);
2105 Finally a pair of macros are provided to tell you if a particular image
2106 row or column appears in a given pass:
2108 int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass);
2109 int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass);
2111 Bear in mind that you will probably also need to check the width and height
2112 of the pass in addition to the above to be sure the pass even exists!
2114 With any luck you are convinced by now that you don't want to do your own
2115 interlace handling. In reality normally the only good reason for doing this
2116 is if you are processing PNG files on a pixel-by-pixel basis and don't want
2117 to load the whole file into memory when it is interlaced.
2119 libpng includes a test program, pngvalid, that illustrates reading and
2120 writing of interlaced images. If you can't get interlacing to work in your
2121 code and don't want to leave it to libpng (the recommended approach), see
2122 how pngvalid.c does it.
2124 Finishing a sequential read
2126 After you are finished reading the image through the
2127 low-level interface, you can finish reading the file. If you are
2128 interested in comments or time, which may be stored either before or
2129 after the image data, you should pass the separate png_info struct if
2130 you want to keep the comments from before and after the image
2133 png_infop end_info = png_create_info_struct(png_ptr);
2137 png_destroy_read_struct(&png_ptr, &info_ptr,
2142 png_read_end(png_ptr, end_info);
2144 If you are not interested, you should still call png_read_end()
2145 but you can pass NULL, avoiding the need to create an end_info structure.
2147 png_read_end(png_ptr, (png_infop)NULL);
2149 If you don't call png_read_end(), then your file pointer will be
2150 left pointing to the first chunk after the last IDAT, which is probably
2151 not what you want if you expect to read something beyond the end of
2154 When you are done, you can free all memory allocated by libpng like this:
2156 png_destroy_read_struct(&png_ptr, &info_ptr,
2159 or, if you didn't create an end_info structure,
2161 png_destroy_read_struct(&png_ptr, &info_ptr,
2164 It is also possible to individually free the info_ptr members that
2165 point to libpng-allocated storage with the following function:
2167 png_free_data(png_ptr, info_ptr, mask, seq)
2169 mask - identifies data to be freed, a mask
2170 containing the bitwise OR of one or
2172 PNG_FREE_PLTE, PNG_FREE_TRNS,
2173 PNG_FREE_HIST, PNG_FREE_ICCP,
2174 PNG_FREE_PCAL, PNG_FREE_ROWS,
2175 PNG_FREE_SCAL, PNG_FREE_SPLT,
2176 PNG_FREE_TEXT, PNG_FREE_UNKN,
2177 or simply PNG_FREE_ALL
2179 seq - sequence number of item to be freed
2182 This function may be safely called when the relevant storage has
2183 already been freed, or has not yet been allocated, or was allocated
2184 by the user and not by libpng, and will in those cases do nothing.
2185 The "seq" parameter is ignored if only one item of the selected data
2186 type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
2187 are allowed for the data type identified in the mask, such as text or
2188 sPLT, only the n'th item in the structure is freed, where n is "seq".
2190 The default behavior is only to free data that was allocated internally
2191 by libpng. This can be changed, so that libpng will not free the data,
2192 or so that it will free data that was allocated by the user with png_malloc()
2193 or png_calloc() and passed in via a png_set_*() function, with
2195 png_data_freer(png_ptr, info_ptr, freer, mask)
2198 PNG_DESTROY_WILL_FREE_DATA
2199 PNG_SET_WILL_FREE_DATA
2200 PNG_USER_WILL_FREE_DATA
2202 mask - which data elements are affected
2203 same choices as in png_free_data()
2205 This function only affects data that has already been allocated.
2206 You can call this function after reading the PNG data but before calling
2207 any png_set_*() functions, to control whether the user or the png_set_*()
2208 function is responsible for freeing any existing data that might be present,
2209 and again after the png_set_*() functions to control whether the user
2210 or png_destroy_*() is supposed to free the data. When the user assumes
2211 responsibility for libpng-allocated data, the application must use
2212 png_free() to free it, and when the user transfers responsibility to libpng
2213 for data that the user has allocated, the user must have used png_malloc()
2214 or png_calloc() to allocate it.
2216 If you allocated your row_pointers in a single block, as suggested above in
2217 the description of the high level read interface, you must not transfer
2218 responsibility for freeing it to the png_set_rows or png_read_destroy function,
2219 because they would also try to free the individual row_pointers[i].
2221 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
2222 separately, do not transfer responsibility for freeing text_ptr to libpng,
2223 because when libpng fills a png_text structure it combines these members with
2224 the key member, and png_free_data() will free only text_ptr.key. Similarly,
2225 if you transfer responsibility for free'ing text_ptr from libpng to your
2226 application, your application must not separately free those members.
2228 The png_free_data() function will turn off the "valid" flag for anything
2229 it frees. If you need to turn the flag off for a chunk that was freed by
2230 your application instead of by libpng, you can use
2232 png_set_invalid(png_ptr, info_ptr, mask);
2234 mask - identifies the chunks to be made invalid,
2235 containing the bitwise OR of one or
2237 PNG_INFO_gAMA, PNG_INFO_sBIT,
2238 PNG_INFO_cHRM, PNG_INFO_PLTE,
2239 PNG_INFO_tRNS, PNG_INFO_bKGD,
2240 PNG_INFO_hIST, PNG_INFO_pHYs,
2241 PNG_INFO_oFFs, PNG_INFO_tIME,
2242 PNG_INFO_pCAL, PNG_INFO_sRGB,
2243 PNG_INFO_iCCP, PNG_INFO_sPLT,
2244 PNG_INFO_sCAL, PNG_INFO_IDAT
2246 For a more compact example of reading a PNG image, see the file example.c.
2248 Reading PNG files progressively
2250 The progressive reader is slightly different then the non-progressive
2251 reader. Instead of calling png_read_info(), png_read_rows(), and
2252 png_read_end(), you make one call to png_process_data(), which calls
2253 callbacks when it has the info, a row, or the end of the image. You
2254 set up these callbacks with png_set_progressive_read_fn(). You don't
2255 have to worry about the input/output functions of libpng, as you are
2256 giving the library the data directly in png_process_data(). I will
2257 assume that you have read the section on reading PNG files above,
2258 so I will only highlight the differences (although I will show
2261 png_structp png_ptr;
2264 /* An example code fragment of how you would
2265 initialize the progressive reader in your
2268 initialize_png_reader()
2270 png_ptr = png_create_read_struct
2271 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2272 user_error_fn, user_warning_fn);
2277 info_ptr = png_create_info_struct(png_ptr);
2281 png_destroy_read_struct(&png_ptr,
2282 (png_infopp)NULL, (png_infopp)NULL);
2286 if (setjmp(png_jmpbuf(png_ptr)))
2288 png_destroy_read_struct(&png_ptr, &info_ptr,
2293 /* This one's new. You can provide functions
2294 to be called when the header info is valid,
2295 when each row is completed, and when the image
2296 is finished. If you aren't using all functions,
2297 you can specify NULL parameters. Even when all
2298 three functions are NULL, you need to call
2299 png_set_progressive_read_fn(). You can use
2300 any struct as the user_ptr (cast to a void pointer
2301 for the function call), and retrieve the pointer
2302 from inside the callbacks using the function
2304 png_get_progressive_ptr(png_ptr);
2306 which will return a void pointer, which you have
2307 to cast appropriately.
2309 png_set_progressive_read_fn(png_ptr, (void *)user_ptr,
2310 info_callback, row_callback, end_callback);
2315 /* A code fragment that you call as you receive blocks
2318 process_data(png_bytep buffer, png_uint_32 length)
2320 if (setjmp(png_jmpbuf(png_ptr)))
2322 png_destroy_read_struct(&png_ptr, &info_ptr,
2327 /* This one's new also. Simply give it a chunk
2328 of data from the file stream (in order, of
2329 course). On machines with segmented memory
2330 models machines, don't give it any more than
2331 64K. The library seems to run fine with sizes
2332 of 4K. Although you can give it much less if
2333 necessary (I assume you can give it chunks of
2334 1 byte, I haven't tried less then 256 bytes
2335 yet). When this function returns, you may
2336 want to display any rows that were generated
2337 in the row callback if you don't already do
2340 png_process_data(png_ptr, info_ptr, buffer, length);
2342 /* At this point you can call png_process_data_skip if
2343 you want to handle data the library will skip yourself;
2344 it simply returns the number of bytes to skip (and stops
2345 libpng skipping that number of bytes on the next
2346 png_process_data call).
2350 /* This function is called (as set by
2351 png_set_progressive_read_fn() above) when enough data
2352 has been supplied so all of the header has been
2356 info_callback(png_structp png_ptr, png_infop info)
2358 /* Do any setup here, including setting any of
2359 the transformations mentioned in the Reading
2360 PNG files section. For now, you _must_ call
2361 either png_start_read_image() or
2362 png_read_update_info() after all the
2363 transformations are set (even if you don't set
2364 any). You may start getting rows before
2365 png_process_data() returns, so this is your
2366 last chance to prepare for that.
2368 This is where you turn on interlace handling,
2369 assuming you don't want to do it yourself.
2371 If you need to you can stop the processing of
2372 your original input data at this point by calling
2373 png_process_data_pause. This returns the number
2374 of unprocessed bytes from the last png_process_data
2375 call - it is up to you to ensure that the next call
2376 sees these bytes again. If you don't want to bother
2377 with this you can get libpng to cache the unread
2378 bytes by setting the 'save' parameter (see png.h) but
2379 then libpng will have to copy the data internally.
2383 /* This function is called when each row of image
2386 row_callback(png_structp png_ptr, png_bytep new_row,
2387 png_uint_32 row_num, int pass)
2389 /* If the image is interlaced, and you turned
2390 on the interlace handler, this function will
2391 be called for every row in every pass. Some
2392 of these rows will not be changed from the
2393 previous pass. When the row is not changed,
2394 the new_row variable will be NULL. The rows
2395 and passes are called in order, so you don't
2396 really need the row_num and pass, but I'm
2397 supplying them because it may make your life
2400 If you did not turn on interlace handling then
2401 the callback is called for each row of each
2402 sub-image when the image is interlaced. In this
2403 case 'row_num' is the row in the sub-image, not
2404 the row in the output image as it is in all other
2407 For the non-NULL rows of interlaced images when
2408 you have switched on libpng interlace handling,
2409 you must call png_progressive_combine_row()
2410 passing in the row and the old row. You can
2411 call this function for NULL rows (it will just
2412 return) and for non-interlaced images (it just
2413 does the memcpy for you) if it will make the
2414 code easier. Thus, you can just do this for
2415 all cases if you switch on interlace handling;
2418 png_progressive_combine_row(png_ptr, old_row,
2421 /* where old_row is what was displayed for
2422 previously for the row. Note that the first
2423 pass (pass == 0, really) will completely cover
2424 the old row, so the rows do not have to be
2425 initialized. After the first pass (and only
2426 for interlaced images), you will have to pass
2427 the current row, and the function will combine
2428 the old row and the new row.
2430 You can also call png_process_data_pause in this
2431 callback - see above.
2436 end_callback(png_structp png_ptr, png_infop info)
2438 /* This function is called after the whole image
2439 has been read, including any chunks after the
2440 image (up to and including the IEND). You
2441 will usually have the same info chunk as you
2442 had in the header, although some data may have
2443 been added to the comments and time fields.
2445 Most people won't do much here, perhaps setting
2446 a flag that marks the image as finished.
2454 Much of this is very similar to reading. However, everything of
2455 importance is repeated here, so you won't have to constantly look
2456 back up in the reading section to understand writing.
2460 You will want to do the I/O initialization before you get into libpng,
2461 so if it doesn't work, you don't have anything to undo. If you are not
2462 using the standard I/O functions, you will need to replace them with
2463 custom writing functions. See the discussion under Customizing libpng.
2465 FILE *fp = fopen(file_name, "wb");
2470 Next, png_struct and png_info need to be allocated and initialized.
2471 As these can be both relatively large, you may not want to store these
2472 on the stack, unless you have stack space to spare. Of course, you
2473 will want to check if they return NULL. If you are also reading,
2474 you won't want to name your read structure and your write structure
2475 both "png_ptr"; you can call them anything you like, such as
2476 "read_ptr" and "write_ptr". Look at pngtest.c, for example.
2478 png_structp png_ptr = png_create_write_struct
2479 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2480 user_error_fn, user_warning_fn);
2485 png_infop info_ptr = png_create_info_struct(png_ptr);
2488 png_destroy_write_struct(&png_ptr,
2493 If you want to use your own memory allocation routines,
2494 define PNG_USER_MEM_SUPPORTED and use
2495 png_create_write_struct_2() instead of png_create_write_struct():
2497 png_structp png_ptr = png_create_write_struct_2
2498 (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,
2499 user_error_fn, user_warning_fn, (png_voidp)
2500 user_mem_ptr, user_malloc_fn, user_free_fn);
2502 After you have these structures, you will need to set up the
2503 error handling. When libpng encounters an error, it expects to
2504 longjmp() back to your routine. Therefore, you will need to call
2505 setjmp() and pass the png_jmpbuf(png_ptr). If you
2506 write the file from different routines, you will need to update
2507 the png_jmpbuf(png_ptr) every time you enter a new routine that will
2508 call a png_*() function. See your documentation of setjmp/longjmp
2509 for your compiler for more information on setjmp/longjmp. See
2510 the discussion on libpng error handling in the Customizing Libpng
2511 section below for more information on the libpng error handling.
2513 if (setjmp(png_jmpbuf(png_ptr)))
2515 png_destroy_write_struct(&png_ptr, &info_ptr);
2522 If you would rather avoid the complexity of setjmp/longjmp issues,
2523 you can compile libpng with PNG_NO_SETJMP, in which case
2524 errors will result in a call to PNG_ABORT() which defaults to abort().
2526 You can #define PNG_ABORT() to a function that does something
2527 more useful than abort(), as long as your function does not
2530 Now you need to set up the output code. The default for libpng is to
2531 use the C function fwrite(). If you use this, you will need to pass a
2532 valid FILE * in the function png_init_io(). Be sure that the file is
2533 opened in binary mode. Again, if you wish to handle writing data in
2534 another way, see the discussion on libpng I/O handling in the Customizing
2535 Libpng section below.
2537 png_init_io(png_ptr, fp);
2539 If you are embedding your PNG into a datastream such as MNG, and don't
2540 want libpng to write the 8-byte signature, or if you have already
2541 written the signature in your application, use
2543 png_set_sig_bytes(png_ptr, 8);
2545 to inform libpng that it should not write a signature.
2549 At this point, you can set up a callback function that will be
2550 called after each row has been written, which you can use to control
2551 a progress meter or the like. It's demonstrated in pngtest.c.
2552 You must supply a function
2554 void write_row_callback(png_structp png_ptr, png_uint_32 row,
2557 /* put your code here */
2560 (You can give it another name that you like instead of "write_row_callback")
2562 To inform libpng about your function, use
2564 png_set_write_status_fn(png_ptr, write_row_callback);
2566 When this function is called the row has already been completely processed and
2567 it has also been written out. The 'row' and 'pass' refer to the next row to be
2569 non-interlaced case the row that was just handled is simply one less than the
2570 passed in row number, and pass will always be 0. For the interlaced case the
2571 same applies unless the row value is 0, in which case the row just handled was
2572 the last one from one of the preceding passes. Because interlacing may skip a
2573 pass you cannot be sure that the preceding pass is just 'pass-1', if you really
2574 need to know what the last pass is record (row,pass) from the callback and use
2575 the last recorded value each time.
2577 As with the user transform you can find the output row using the
2578 PNG_ROW_FROM_PASS_ROW macro.
2580 You now have the option of modifying how the compression library will
2581 run. The following functions are mainly for testing, but may be useful
2582 in some cases, like if you need to write PNG files extremely fast and
2583 are willing to give up some compression, or if you want to get the
2584 maximum possible compression at the expense of slower writing. If you
2585 have no special needs in this area, let the library do what it wants by
2586 not calling this function at all, as it has been tuned to deliver a good
2587 speed/compression ratio. The second parameter to png_set_filter() is
2588 the filter method, for which the only valid values are 0 (as of the
2589 July 1999 PNG specification, version 1.2) or 64 (if you are writing
2590 a PNG datastream that is to be embedded in a MNG datastream). The third
2591 parameter is a flag that indicates which filter type(s) are to be tested
2592 for each scanline. See the PNG specification for details on the specific
2596 /* turn on or off filtering, and/or choose
2597 specific filters. You can use either a single
2598 PNG_FILTER_VALUE_NAME or the bitwise OR of one
2599 or more PNG_FILTER_NAME masks.
2601 png_set_filter(png_ptr, 0,
2602 PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE |
2603 PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB |
2604 PNG_FILTER_UP | PNG_FILTER_VALUE_UP |
2605 PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG |
2606 PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH|
2609 If an application wants to start and stop using particular filters during
2610 compression, it should start out with all of the filters (to ensure that
2611 the previous row of pixels will be stored in case it's needed later),
2612 and then add and remove them after the start of compression.
2614 If you are writing a PNG datastream that is to be embedded in a MNG
2615 datastream, the second parameter can be either 0 or 64.
2617 The png_set_compression_*() functions interface to the zlib compression
2618 library, and should mostly be ignored unless you really know what you are
2619 doing. The only generally useful call is png_set_compression_level()
2620 which changes how much time zlib spends on trying to compress the image
2621 data. See the Compression Library (zlib.h and algorithm.txt, distributed
2622 with zlib) for details on the compression levels.
2626 /* Set the zlib compression level */
2627 png_set_compression_level(png_ptr,
2628 Z_BEST_COMPRESSION);
2630 /* Set other zlib parameters for compressing IDAT */
2631 png_set_compression_mem_level(png_ptr, 8);
2632 png_set_compression_strategy(png_ptr,
2633 Z_DEFAULT_STRATEGY);
2634 png_set_compression_window_bits(png_ptr, 15);
2635 png_set_compression_method(png_ptr, 8);
2636 png_set_compression_buffer_size(png_ptr, 8192)
2638 /* Set zlib parameters for text compression
2639 * If you don't call these, the parameters
2640 * fall back on those defined for IDAT chunks
2642 png_set_text_compression_mem_level(png_ptr, 8);
2643 png_set_text_compression_strategy(png_ptr,
2644 Z_DEFAULT_STRATEGY);
2645 png_set_text_compression_window_bits(png_ptr, 15);
2646 png_set_text_compression_method(png_ptr, 8);
2648 Setting the contents of info for output
2650 You now need to fill in the png_info structure with all the data you
2651 wish to write before the actual image. Note that the only thing you
2652 are allowed to write after the image is the text chunks and the time
2653 chunk (as of PNG Specification 1.2, anyway). See png_write_end() and
2654 the latest PNG specification for more information on that. If you
2655 wish to write them before the image, fill them in now, and flag that
2656 data as being valid. If you want to wait until after the data, don't
2657 fill them until png_write_end(). For all the fields in png_info and
2658 their data types, see png.h. For explanations of what the fields
2659 contain, see the PNG specification.
2661 Some of the more important parts of the png_info are:
2663 png_set_IHDR(png_ptr, info_ptr, width, height,
2664 bit_depth, color_type, interlace_type,
2665 compression_type, filter_method)
2667 width - holds the width of the image
2668 in pixels (up to 2^31).
2670 height - holds the height of the image
2671 in pixels (up to 2^31).
2673 bit_depth - holds the bit depth of one of the
2675 (valid values are 1, 2, 4, 8, 16
2676 and depend also on the
2677 color_type. See also significant
2680 color_type - describes which color/alpha
2681 channels are present.
2683 (bit depths 1, 2, 4, 8, 16)
2684 PNG_COLOR_TYPE_GRAY_ALPHA
2686 PNG_COLOR_TYPE_PALETTE
2687 (bit depths 1, 2, 4, 8)
2690 PNG_COLOR_TYPE_RGB_ALPHA
2693 PNG_COLOR_MASK_PALETTE
2694 PNG_COLOR_MASK_COLOR
2695 PNG_COLOR_MASK_ALPHA
2697 interlace_type - PNG_INTERLACE_NONE or
2700 compression_type - (must be
2701 PNG_COMPRESSION_TYPE_DEFAULT)
2703 filter_method - (must be PNG_FILTER_TYPE_DEFAULT
2704 or, if you are writing a PNG to
2705 be embedded in a MNG datastream,
2707 PNG_INTRAPIXEL_DIFFERENCING)
2709 If you call png_set_IHDR(), the call must appear before any of the
2710 other png_set_*() functions, because they might require access to some of
2711 the IHDR settings. The remaining png_set_*() functions can be called
2714 If you wish, you can reset the compression_type, interlace_type, or
2715 filter_method later by calling png_set_IHDR() again; if you do this, the
2716 width, height, bit_depth, and color_type must be the same in each call.
2718 png_set_PLTE(png_ptr, info_ptr, palette,
2721 palette - the palette for the file
2722 (array of png_color)
2723 num_palette - number of entries in the palette
2725 png_set_gAMA(png_ptr, info_ptr, file_gamma);
2726 png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma);
2728 file_gamma - the gamma at which the image was
2729 created (PNG_INFO_gAMA)
2731 int_file_gamma - 100,000 times the gamma at which
2732 the image was created
2734 png_set_cHRM(png_ptr, info_ptr, white_x, white_y, red_x, red_y,
2735 green_x, green_y, blue_x, blue_y)
2736 png_set_cHRM_XYZ(png_ptr, info_ptr, red_X, red_Y, red_Z, green_X,
2737 green_Y, green_Z, blue_X, blue_Y, blue_Z)
2738 png_set_cHRM_fixed(png_ptr, info_ptr, int_white_x, int_white_y,
2739 int_red_x, int_red_y, int_green_x, int_green_y,
2740 int_blue_x, int_blue_y)
2741 png_set_cHRM_XYZ_fixed(png_ptr, info_ptr, int_red_X, int_red_Y,
2742 int_red_Z, int_green_X, int_green_Y, int_green_Z,
2743 int_blue_X, int_blue_Y, int_blue_Z)
2745 {white,red,green,blue}_{x,y}
2746 A color space encoding specified using the chromaticities
2747 of the end points and the white point.
2749 {red,green,blue}_{X,Y,Z}
2750 A color space encoding specified using the encoding end
2751 points - the CIE tristimulus specification of the intended
2752 color of the red, green and blue channels in the PNG RGB
2753 data. The white point is simply the sum of the three end
2756 png_set_sRGB(png_ptr, info_ptr, srgb_intent);
2758 srgb_intent - the rendering intent
2759 (PNG_INFO_sRGB) The presence of
2760 the sRGB chunk means that the pixel
2761 data is in the sRGB color space.
2762 This chunk also implies specific
2763 values of gAMA and cHRM. Rendering
2764 intent is the CSS-1 property that
2765 has been defined by the International
2767 (http://www.color.org).
2769 PNG_sRGB_INTENT_SATURATION,
2770 PNG_sRGB_INTENT_PERCEPTUAL,
2771 PNG_sRGB_INTENT_ABSOLUTE, or
2772 PNG_sRGB_INTENT_RELATIVE.
2775 png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr,
2778 srgb_intent - the rendering intent
2779 (PNG_INFO_sRGB) The presence of the
2780 sRGB chunk means that the pixel
2781 data is in the sRGB color space.
2782 This function also causes gAMA and
2783 cHRM chunks with the specific values
2784 that are consistent with sRGB to be
2787 png_set_iCCP(png_ptr, info_ptr, name, compression_type,
2790 name - The profile name.
2792 compression_type - The compression type; always
2793 PNG_COMPRESSION_TYPE_BASE for PNG 1.0.
2794 You may give NULL to this argument to
2797 profile - International Color Consortium color
2798 profile data. May contain NULs.
2800 proflen - length of profile data in bytes.
2802 png_set_sBIT(png_ptr, info_ptr, sig_bit);
2804 sig_bit - the number of significant bits for
2805 (PNG_INFO_sBIT) each of the gray, red,
2806 green, and blue channels, whichever are
2807 appropriate for the given color type
2810 png_set_tRNS(png_ptr, info_ptr, trans_alpha,
2811 num_trans, trans_color);
2813 trans_alpha - array of alpha (transparency)
2814 entries for palette (PNG_INFO_tRNS)
2816 num_trans - number of transparent entries
2819 trans_color - graylevel or color sample values
2820 (in order red, green, blue) of the
2821 single transparent color for
2822 non-paletted images (PNG_INFO_tRNS)
2824 png_set_hIST(png_ptr, info_ptr, hist);
2826 hist - histogram of palette (array of
2827 png_uint_16) (PNG_INFO_hIST)
2829 png_set_tIME(png_ptr, info_ptr, mod_time);
2831 mod_time - time image was last modified
2834 png_set_bKGD(png_ptr, info_ptr, background);
2836 background - background color (of type
2837 png_color_16p) (PNG_VALID_bKGD)
2839 png_set_text(png_ptr, info_ptr, text_ptr, num_text);
2841 text_ptr - array of png_text holding image
2844 text_ptr[i].compression - type of compression used
2845 on "text" PNG_TEXT_COMPRESSION_NONE
2846 PNG_TEXT_COMPRESSION_zTXt
2847 PNG_ITXT_COMPRESSION_NONE
2848 PNG_ITXT_COMPRESSION_zTXt
2849 text_ptr[i].key - keyword for comment. Must contain
2851 text_ptr[i].text - text comments for current
2852 keyword. Can be NULL or empty.
2853 text_ptr[i].text_length - length of text string,
2854 after decompression, 0 for iTXt
2855 text_ptr[i].itxt_length - length of itxt string,
2856 after decompression, 0 for tEXt/zTXt
2857 text_ptr[i].lang - language of comment (NULL or
2859 text_ptr[i].translated_keyword - keyword in UTF-8 (NULL
2860 or empty for unknown).
2862 Note that the itxt_length, lang, and lang_key
2863 members of the text_ptr structure only exist when the
2864 library is built with iTXt chunk support. Prior to
2865 libpng-1.4.0 the library was built by default without
2866 iTXt support. Also note that when iTXt is supported,
2867 they contain NULL pointers when the "compression"
2868 field contains PNG_TEXT_COMPRESSION_NONE or
2869 PNG_TEXT_COMPRESSION_zTXt.
2871 num_text - number of comments
2873 png_set_sPLT(png_ptr, info_ptr, &palette_ptr,
2876 palette_ptr - array of png_sPLT_struct structures
2877 to be added to the list of palettes
2878 in the info structure.
2879 num_spalettes - number of palette structures to be
2882 png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y,
2885 offset_x - positive offset from the left
2888 offset_y - positive offset from the top
2891 unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER
2893 png_set_pHYs(png_ptr, info_ptr, res_x, res_y,
2896 res_x - pixels/unit physical resolution
2899 res_y - pixels/unit physical resolution
2902 unit_type - PNG_RESOLUTION_UNKNOWN,
2903 PNG_RESOLUTION_METER
2905 png_set_sCAL(png_ptr, info_ptr, unit, width, height)
2907 unit - physical scale units (an integer)
2909 width - width of a pixel in physical scale units
2911 height - height of a pixel in physical scale units
2912 (width and height are doubles)
2914 png_set_sCAL_s(png_ptr, info_ptr, unit, width, height)
2916 unit - physical scale units (an integer)
2918 width - width of a pixel in physical scale units
2919 expressed as a string
2921 height - height of a pixel in physical scale units
2922 (width and height are strings like "2.54")
2924 png_set_unknown_chunks(png_ptr, info_ptr, &unknowns,
2927 unknowns - array of png_unknown_chunk
2928 structures holding unknown chunks
2929 unknowns[i].name - name of unknown chunk
2930 unknowns[i].data - data of unknown chunk
2931 unknowns[i].size - size of unknown chunk's data
2932 unknowns[i].location - position to write chunk in file
2933 0: do not write chunk
2934 PNG_HAVE_IHDR: before PLTE
2935 PNG_HAVE_PLTE: before IDAT
2936 PNG_AFTER_IDAT: after IDAT
2938 The "location" member is set automatically according to
2939 what part of the output file has already been written.
2940 You can change its value after calling png_set_unknown_chunks()
2941 as demonstrated in pngtest.c. Within each of the "locations",
2942 the chunks are sequenced according to their position in the
2943 structure (that is, the value of "i", which is the order in which
2944 the chunk was either read from the input file or defined with
2945 png_set_unknown_chunks).
2947 A quick word about text and num_text. text is an array of png_text
2948 structures. num_text is the number of valid structures in the array.
2949 Each png_text structure holds a language code, a keyword, a text value,
2950 and a compression type.
2952 The compression types have the same valid numbers as the compression
2953 types of the image data. Currently, the only valid number is zero.
2954 However, you can store text either compressed or uncompressed, unlike
2955 images, which always have to be compressed. So if you don't want the
2956 text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE.
2957 Because tEXt and zTXt chunks don't have a language field, if you
2958 specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt
2959 any language code or translated keyword will not be written out.
2961 Until text gets around a few hundred bytes, it is not worth compressing it.
2962 After the text has been written out to the file, the compression type
2963 is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR,
2964 so that it isn't written out again at the end (in case you are calling
2965 png_write_end() with the same struct).
2967 The keywords that are given in the PNG Specification are:
2969 Title Short (one line) title or
2972 Author Name of image's creator
2974 Description Description of image (possibly long)
2976 Copyright Copyright notice
2978 Creation Time Time of original image creation
2979 (usually RFC 1123 format, see below)
2981 Software Software used to create the image
2983 Disclaimer Legal disclaimer
2985 Warning Warning of nature of content
2987 Source Device used to create the image
2989 Comment Miscellaneous comment; conversion
2990 from other image format
2992 The keyword-text pairs work like this. Keywords should be short
2993 simple descriptions of what the comment is about. Some typical
2994 keywords are found in the PNG specification, as is some recommendations
2995 on keywords. You can repeat keywords in a file. You can even write
2996 some text before the image and some after. For example, you may want
2997 to put a description of the image before the image, but leave the
2998 disclaimer until after, so viewers working over modem connections
2999 don't have to wait for the disclaimer to go over the modem before
3000 they start seeing the image. Finally, keywords should be full
3001 words, not abbreviations. Keywords and text are in the ISO 8859-1
3002 (Latin-1) character set (a superset of regular ASCII) and can not
3003 contain NUL characters, and should not contain control or other
3004 unprintable characters. To make the comments widely readable, stick
3005 with basic ASCII, and avoid machine specific character set extensions
3006 like the IBM-PC character set. The keyword must be present, but
3007 you can leave off the text string on non-compressed pairs.
3008 Compressed pairs must have a text string, as only the text string
3009 is compressed anyway, so the compression would be meaningless.
3011 PNG supports modification time via the png_time structure. Two
3012 conversion routines are provided, png_convert_from_time_t() for
3013 time_t and png_convert_from_struct_tm() for struct tm. The
3014 time_t routine uses gmtime(). You don't have to use either of
3015 these, but if you wish to fill in the png_time structure directly,
3016 you should provide the time in universal time (GMT) if possible
3017 instead of your local time. Note that the year number is the full
3018 year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and
3019 that months start with 1.
3021 If you want to store the time of the original image creation, you should
3022 use a plain tEXt chunk with the "Creation Time" keyword. This is
3023 necessary because the "creation time" of a PNG image is somewhat vague,
3024 depending on whether you mean the PNG file, the time the image was
3025 created in a non-PNG format, a still photo from which the image was
3026 scanned, or possibly the subject matter itself. In order to facilitate
3027 machine-readable dates, it is recommended that the "Creation Time"
3028 tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"),
3029 although this isn't a requirement. Unlike the tIME chunk, the
3030 "Creation Time" tEXt chunk is not expected to be automatically changed
3031 by the software. To facilitate the use of RFC 1123 dates, a function
3032 png_convert_to_rfc1123(png_ptr, png_timep) is provided to convert
3033 from PNG time to an RFC 1123 format string.
3035 Writing unknown chunks
3037 You can use the png_set_unknown_chunks function to queue up chunks
3038 for writing. You give it a chunk name, raw data, and a size; that's
3039 all there is to it. The chunks will be written by the next following
3040 png_write_info_before_PLTE, png_write_info, or png_write_end function.
3041 Any chunks previously read into the info structure's unknown-chunk
3042 list will also be written out in a sequence that satisfies the PNG
3043 specification's ordering rules.
3045 The high-level write interface
3047 At this point there are two ways to proceed; through the high-level
3048 write interface, or through a sequence of low-level write operations.
3049 You can use the high-level interface if your image data is present
3050 in the info structure. All defined output
3051 transformations are permitted, enabled by the following masks.
3053 PNG_TRANSFORM_IDENTITY No transformation
3054 PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples
3055 PNG_TRANSFORM_PACKSWAP Change order of packed
3057 PNG_TRANSFORM_INVERT_MONO Invert monochrome images
3058 PNG_TRANSFORM_SHIFT Normalize pixels to the
3060 PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA
3062 PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA
3064 PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity
3066 PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples
3067 PNG_TRANSFORM_STRIP_FILLER Strip out filler
3069 PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading
3071 PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing
3074 If you have valid image data in the info structure (you can use
3075 png_set_rows() to put image data in the info structure), simply do this:
3077 png_write_png(png_ptr, info_ptr, png_transforms, NULL)
3079 where png_transforms is an integer containing the bitwise OR of some set of
3080 transformation flags. This call is equivalent to png_write_info(),
3081 followed the set of transformations indicated by the transform mask,
3082 then png_write_image(), and finally png_write_end().
3084 (The final parameter of this call is not yet used. Someday it might point
3085 to transformation parameters required by some future output transform.)
3087 You must use png_transforms and not call any png_set_transform() functions
3088 when you use png_write_png().
3090 The low-level write interface
3092 If you are going the low-level route instead, you are now ready to
3093 write all the file information up to the actual image data. You do
3094 this with a call to png_write_info().
3096 png_write_info(png_ptr, info_ptr);
3098 Note that there is one transformation you may need to do before
3099 png_write_info(). In PNG files, the alpha channel in an image is the
3100 level of opacity. If your data is supplied as a level of transparency,
3101 you can invert the alpha channel before you write it, so that 0 is
3102 fully transparent and 255 (in 8-bit or paletted images) or 65535
3103 (in 16-bit images) is fully opaque, with
3105 png_set_invert_alpha(png_ptr);
3107 This must appear before png_write_info() instead of later with the
3108 other transformations because in the case of paletted images the tRNS
3109 chunk data has to be inverted before the tRNS chunk is written. If
3110 your image is not a paletted image, the tRNS data (which in such cases
3111 represents a single color to be rendered as transparent) won't need to
3112 be changed, and you can safely do this transformation after your
3113 png_write_info() call.
3115 If you need to write a private chunk that you want to appear before
3116 the PLTE chunk when PLTE is present, you can write the PNG info in
3117 two steps, and insert code to write your own chunk between them:
3119 png_write_info_before_PLTE(png_ptr, info_ptr);
3120 png_set_unknown_chunks(png_ptr, info_ptr, ...);
3121 png_write_info(png_ptr, info_ptr);
3123 After you've written the file information, you can set up the library
3124 to handle any special transformations of the image data. The various
3125 ways to transform the data will be described in the order that they
3126 should occur. This is important, as some of these change the color
3127 type and/or bit depth of the data, and some others only work on
3128 certain color types and bit depths. Even though each transformation
3129 checks to see if it has data that it can do something with, you should
3130 make sure to only enable a transformation if it will be valid for the
3131 data. For example, don't swap red and blue on grayscale data.
3133 PNG files store RGB pixels packed into 3 or 6 bytes. This code tells
3134 the library to strip input data that has 4 or 8 bytes per pixel down
3135 to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2
3138 png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE);
3140 where the 0 is unused, and the location is either PNG_FILLER_BEFORE or
3141 PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel
3142 is stored XRGB or RGBX.
3144 PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as
3145 they can, resulting in, for example, 8 pixels per byte for 1 bit files.
3146 If the data is supplied at 1 pixel per byte, use this code, which will
3147 correctly pack the pixels into a single byte:
3149 png_set_packing(png_ptr);
3151 PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your
3152 data is of another bit depth, you can write an sBIT chunk into the
3153 file so that decoders can recover the original data if desired.
3155 /* Set the true bit depth of the image data */
3156 if (color_type & PNG_COLOR_MASK_COLOR)
3158 sig_bit.red = true_bit_depth;
3159 sig_bit.green = true_bit_depth;
3160 sig_bit.blue = true_bit_depth;
3165 sig_bit.gray = true_bit_depth;
3168 if (color_type & PNG_COLOR_MASK_ALPHA)
3170 sig_bit.alpha = true_bit_depth;
3173 png_set_sBIT(png_ptr, info_ptr, &sig_bit);
3175 If the data is stored in the row buffer in a bit depth other than
3176 one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG),
3177 this will scale the values to appear to be the correct bit depth as
3180 png_set_shift(png_ptr, &sig_bit);
3182 PNG files store 16-bit pixels in network byte order (big-endian,
3183 ie. most significant bits first). This code would be used if they are
3184 supplied the other way (little-endian, i.e. least significant bits
3185 first, the way PCs store them):
3188 png_set_swap(png_ptr);
3190 If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you
3191 need to change the order the pixels are packed into bytes, you can use:
3194 png_set_packswap(png_ptr);
3196 PNG files store 3 color pixels in red, green, blue order. This code
3197 would be used if they are supplied as blue, green, red:
3199 png_set_bgr(png_ptr);
3201 PNG files describe monochrome as black being zero and white being
3202 one. This code would be used if the pixels are supplied with this reversed
3203 (black being one and white being zero):
3205 png_set_invert_mono(png_ptr);
3207 Finally, you can write your own transformation function if none of
3208 the existing ones meets your needs. This is done by setting a callback
3211 png_set_write_user_transform_fn(png_ptr,
3212 write_transform_fn);
3214 You must supply the function
3216 void write_transform_fn(png_structp png_ptr, png_row_infop
3217 row_info, png_bytep data)
3219 See pngtest.c for a working example. Your function will be called
3220 before any of the other transformations are processed. If supported
3221 libpng also supplies an information routine that may be called from
3224 png_get_current_row_number(png_ptr);
3225 png_get_current_pass_number(png_ptr);
3227 This returns the current row passed to the transform. With interlaced
3228 images the value returned is the row in the input sub-image image. Use
3229 PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to
3230 find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass).
3232 The discussion of interlace handling above contains more information on how to
3235 You can also set up a pointer to a user structure for use by your
3238 png_set_user_transform_info(png_ptr, user_ptr, 0, 0);
3240 The user_channels and user_depth parameters of this function are ignored
3241 when writing; you can set them to zero as shown.
3243 You can retrieve the pointer via the function png_get_user_transform_ptr().
3246 voidp write_user_transform_ptr =
3247 png_get_user_transform_ptr(png_ptr);
3249 It is possible to have libpng flush any pending output, either manually,
3250 or automatically after a certain number of lines have been written. To
3251 flush the output stream a single time call:
3253 png_write_flush(png_ptr);
3255 and to have libpng flush the output stream periodically after a certain
3256 number of scanlines have been written, call:
3258 png_set_flush(png_ptr, nrows);
3260 Note that the distance between rows is from the last time png_write_flush()
3261 was called, or the first row of the image if it has never been called.
3262 So if you write 50 lines, and then png_set_flush 25, it will flush the
3263 output on the next scanline, and every 25 lines thereafter, unless
3264 png_write_flush() is called before 25 more lines have been written.
3265 If nrows is too small (less than about 10 lines for a 640 pixel wide
3266 RGB image) the image compression may decrease noticeably (although this
3267 may be acceptable for real-time applications). Infrequent flushing will
3268 only degrade the compression performance by a few percent over images
3269 that do not use flushing.
3271 Writing the image data
3273 That's it for the transformations. Now you can write the image data.
3274 The simplest way to do this is in one function call. If you have the
3275 whole image in memory, you can just call png_write_image() and libpng
3276 will write the image. You will need to pass in an array of pointers to
3277 each row. This function automatically handles interlacing, so you don't
3278 need to call png_set_interlace_handling() or call this function multiple
3279 times, or any of that other stuff necessary with png_write_rows().
3281 png_write_image(png_ptr, row_pointers);
3283 where row_pointers is:
3285 png_byte *row_pointers[height];
3287 You can point to void or char or whatever you use for pixels.
3289 If you don't want to write the whole image at once, you can
3290 use png_write_rows() instead. If the file is not interlaced,
3293 png_write_rows(png_ptr, row_pointers,
3296 row_pointers is the same as in the png_write_image() call.
3298 If you are just writing one row at a time, you can do this with
3299 a single row_pointer instead of an array of row_pointers:
3301 png_bytep row_pointer = row;
3303 png_write_row(png_ptr, row_pointer);
3305 When the file is interlaced, things can get a good deal more complicated.
3306 The only currently (as of the PNG Specification version 1.2, dated July
3307 1999) defined interlacing scheme for PNG files is the "Adam7" interlace
3308 scheme, that breaks down an image into seven smaller images of varying
3309 size. libpng will build these images for you, or you can do them
3310 yourself. If you want to build them yourself, see the PNG specification
3311 for details of which pixels to write when.
3313 If you don't want libpng to handle the interlacing details, just
3314 use png_set_interlace_handling() and call png_write_rows() the
3315 correct number of times to write all the sub-images
3316 (png_set_interlace_handling() returns the number of sub-images.)
3318 If you want libpng to build the sub-images, call this before you start
3321 number_of_passes = png_set_interlace_handling(png_ptr);
3323 This will return the number of passes needed. Currently, this is seven,
3324 but may change if another interlace type is added.
3326 Then write the complete image number_of_passes times.
3328 png_write_rows(png_ptr, row_pointers, number_of_rows);
3330 Think carefully before you write an interlaced image. Typically code that
3331 reads such images reads all the image data into memory, uncompressed, before
3332 doing any processing. Only code that can display an image on the fly can
3333 take advantage of the interlacing and even then the image has to be exactly
3334 the correct size for the output device, because scaling an image requires
3335 adjacent pixels and these are not available until all the passes have been
3338 If you do write an interlaced image you will hardly ever need to handle
3339 the interlacing yourself. Call png_set_interlace_handling() and use the
3340 approach described above.
3342 The only time it is conceivable that you will really need to write an
3343 interlaced image pass-by-pass is when you have read one pass by pass and
3344 made some pixel-by-pixel transformation to it, as described in the read
3345 code above. In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros
3346 to determine the size of each sub-image in turn and simply write the rows
3347 you obtained from the read code.
3349 Finishing a sequential write
3351 After you are finished writing the image, you should finish writing
3352 the file. If you are interested in writing comments or time, you should
3353 pass an appropriately filled png_info pointer. If you are not interested,
3356 png_write_end(png_ptr, info_ptr);
3358 When you are done, you can free all memory used by libpng like this:
3360 png_destroy_write_struct(&png_ptr, &info_ptr);
3362 It is also possible to individually free the info_ptr members that
3363 point to libpng-allocated storage with the following function:
3365 png_free_data(png_ptr, info_ptr, mask, seq)
3367 mask - identifies data to be freed, a mask
3368 containing the bitwise OR of one or
3370 PNG_FREE_PLTE, PNG_FREE_TRNS,
3371 PNG_FREE_HIST, PNG_FREE_ICCP,
3372 PNG_FREE_PCAL, PNG_FREE_ROWS,
3373 PNG_FREE_SCAL, PNG_FREE_SPLT,
3374 PNG_FREE_TEXT, PNG_FREE_UNKN,
3375 or simply PNG_FREE_ALL
3377 seq - sequence number of item to be freed
3380 This function may be safely called when the relevant storage has
3381 already been freed, or has not yet been allocated, or was allocated
3382 by the user and not by libpng, and will in those cases do nothing.
3383 The "seq" parameter is ignored if only one item of the selected data
3384 type, such as PLTE, is allowed. If "seq" is not -1, and multiple items
3385 are allowed for the data type identified in the mask, such as text or
3386 sPLT, only the n'th item in the structure is freed, where n is "seq".
3388 If you allocated data such as a palette that you passed in to libpng
3389 with png_set_*, you must not free it until just before the call to
3390 png_destroy_write_struct().
3392 The default behavior is only to free data that was allocated internally
3393 by libpng. This can be changed, so that libpng will not free the data,
3394 or so that it will free data that was allocated by the user with png_malloc()
3395 or png_calloc() and passed in via a png_set_*() function, with
3397 png_data_freer(png_ptr, info_ptr, freer, mask)
3400 PNG_DESTROY_WILL_FREE_DATA
3401 PNG_SET_WILL_FREE_DATA
3402 PNG_USER_WILL_FREE_DATA
3404 mask - which data elements are affected
3405 same choices as in png_free_data()
3407 For example, to transfer responsibility for some data from a read structure
3408 to a write structure, you could use
3410 png_data_freer(read_ptr, read_info_ptr,
3411 PNG_USER_WILL_FREE_DATA,
3412 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3414 png_data_freer(write_ptr, write_info_ptr,
3415 PNG_DESTROY_WILL_FREE_DATA,
3416 PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST)
3418 thereby briefly reassigning responsibility for freeing to the user but
3419 immediately afterwards reassigning it once more to the write_destroy
3420 function. Having done this, it would then be safe to destroy the read
3421 structure and continue to use the PLTE, tRNS, and hIST data in the write
3424 This function only affects data that has already been allocated.
3425 You can call this function before calling after the png_set_*() functions
3426 to control whether the user or png_destroy_*() is supposed to free the data.
3427 When the user assumes responsibility for libpng-allocated data, the
3428 application must use
3429 png_free() to free it, and when the user transfers responsibility to libpng
3430 for data that the user has allocated, the user must have used png_malloc()
3431 or png_calloc() to allocate it.
3433 If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword
3434 separately, do not transfer responsibility for freeing text_ptr to libpng,
3435 because when libpng fills a png_text structure it combines these members with
3436 the key member, and png_free_data() will free only text_ptr.key. Similarly,
3437 if you transfer responsibility for free'ing text_ptr from libpng to your
3438 application, your application must not separately free those members.
3439 For a more compact example of writing a PNG image, see the file example.c.
3441 V. Modifying/Customizing libpng:
3443 There are two issues here. The first is changing how libpng does
3444 standard things like memory allocation, input/output, and error handling.
3445 The second deals with more complicated things like adding new chunks,
3446 adding new transformations, and generally changing how libpng works.
3447 Both of those are compile-time issues; that is, they are generally
3448 determined at the time the code is written, and there is rarely a need
3449 to provide the user with a means of changing them.
3451 Memory allocation, input/output, and error handling
3453 All of the memory allocation, input/output, and error handling in libpng
3454 goes through callbacks that are user-settable. The default routines are
3455 in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change
3456 these functions, call the appropriate png_set_*_fn() function.
3458 Memory allocation is done through the functions png_malloc(), png_calloc(),
3459 and png_free(). The png_malloc() and png_free() functions currently just
3460 call the standard C functions and png_calloc() calls png_malloc() and then
3461 clears the newly allocated memory to zero; note that png_calloc(png_ptr, size)
3462 is not the same as the calloc(number, size) function provided by stdlib.h.
3463 There is limited support for certain systems with segmented memory
3464 architectures and the types of pointers declared by png.h match this; you
3465 will have to use appropriate pointers in your application. Since it is
3466 unlikely that the method of handling memory allocation on a platform
3467 will change between applications, these functions must be modified in
3468 the library at compile time. If you prefer to use a different method
3469 of allocating and freeing data, you can use png_create_read_struct_2() or
3470 png_create_write_struct_2() to register your own functions as described
3471 above. These functions also provide a void pointer that can be retrieved
3474 mem_ptr=png_get_mem_ptr(png_ptr);
3476 Your replacement memory functions must have prototypes as follows:
3478 png_voidp malloc_fn(png_structp png_ptr,
3479 png_alloc_size_t size);
3481 void free_fn(png_structp png_ptr, png_voidp ptr);
3483 Your malloc_fn() must return NULL in case of failure. The png_malloc()
3484 function will normally call png_error() if it receives a NULL from the
3485 system memory allocator or from your replacement malloc_fn().
3487 Your free_fn() will never be called with a NULL ptr, since libpng's
3488 png_free() checks for NULL before calling free_fn().
3490 Input/Output in libpng is done through png_read() and png_write(),
3491 which currently just call fread() and fwrite(). The FILE * is stored in
3492 png_struct and is initialized via png_init_io(). If you wish to change
3493 the method of I/O, the library supplies callbacks that you can set
3494 through the function png_set_read_fn() and png_set_write_fn() at run
3495 time, instead of calling the png_init_io() function. These functions
3496 also provide a void pointer that can be retrieved via the function
3497 png_get_io_ptr(). For example:
3499 png_set_read_fn(png_structp read_ptr,
3500 voidp read_io_ptr, png_rw_ptr read_data_fn)
3502 png_set_write_fn(png_structp write_ptr,
3503 voidp write_io_ptr, png_rw_ptr write_data_fn,
3504 png_flush_ptr output_flush_fn);
3506 voidp read_io_ptr = png_get_io_ptr(read_ptr);
3507 voidp write_io_ptr = png_get_io_ptr(write_ptr);
3509 The replacement I/O functions must have prototypes as follows:
3511 void user_read_data(png_structp png_ptr,
3512 png_bytep data, png_size_t length);
3514 void user_write_data(png_structp png_ptr,
3515 png_bytep data, png_size_t length);
3517 void user_flush_data(png_structp png_ptr);
3519 The user_read_data() function is responsible for detecting and
3520 handling end-of-data errors.
3522 Supplying NULL for the read, write, or flush functions sets them back
3523 to using the default C stream functions, which expect the io_ptr to
3524 point to a standard *FILE structure. It is probably a mistake
3525 to use NULL for one of write_data_fn and output_flush_fn but not both
3526 of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined.
3527 It is an error to read from a write stream, and vice versa.
3529 Error handling in libpng is done through png_error() and png_warning().
3530 Errors handled through png_error() are fatal, meaning that png_error()
3531 should never return to its caller. Currently, this is handled via
3532 setjmp() and longjmp() (unless you have compiled libpng with
3533 PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()),
3534 but you could change this to do things like exit() if you should wish,
3535 as long as your function does not return.
3537 On non-fatal errors, png_warning() is called
3538 to print a warning message, and then control returns to the calling code.
3539 By default png_error() and png_warning() print a message on stderr via
3540 fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined
3541 (because you don't want the messages) or PNG_NO_STDIO defined (because
3542 fprintf() isn't available). If you wish to change the behavior of the error
3543 functions, you will need to set up your own message callbacks. These
3544 functions are normally supplied at the time that the png_struct is created.
3545 It is also possible to redirect errors and warnings to your own replacement
3546 functions after png_create_*_struct() has been called by calling:
3548 png_set_error_fn(png_structp png_ptr,
3549 png_voidp error_ptr, png_error_ptr error_fn,
3550 png_error_ptr warning_fn);
3552 png_voidp error_ptr = png_get_error_ptr(png_ptr);
3554 If NULL is supplied for either error_fn or warning_fn, then the libpng
3555 default function will be used, calling fprintf() and/or longjmp() if a
3556 problem is encountered. The replacement error functions should have
3557 parameters as follows:
3559 void user_error_fn(png_structp png_ptr,
3560 png_const_charp error_msg);
3562 void user_warning_fn(png_structp png_ptr,
3563 png_const_charp warning_msg);
3565 The motivation behind using setjmp() and longjmp() is the C++ throw and
3566 catch exception handling methods. This makes the code much easier to write,
3567 as there is no need to check every return code of every function call.
3568 However, there are some uncertainties about the status of local variables
3569 after a longjmp, so the user may want to be careful about doing anything
3570 after setjmp returns non-zero besides returning itself. Consult your
3571 compiler documentation for more details. For an alternative approach, you
3572 may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net),
3573 which is illustrated in pngvalid.c and in contrib/visupng.
3577 If you need to read or write custom chunks, you may need to get deeper
3578 into the libpng code. The library now has mechanisms for storing
3579 and writing chunks of unknown type; you can even declare callbacks
3580 for custom chunks. However, this may not be good enough if the
3581 library code itself needs to know about interactions between your
3582 chunk and existing `intrinsic' chunks.
3584 If you need to write a new intrinsic chunk, first read the PNG
3585 specification. Acquire a first level of understanding of how it works.
3586 Pay particular attention to the sections that describe chunk names,
3587 and look at how other chunks were designed, so you can do things
3588 similarly. Second, check out the sections of libpng that read and
3589 write chunks. Try to find a chunk that is similar to yours and use
3590 it as a template. More details can be found in the comments inside
3591 the code. It is best to handle private or unknown chunks in a generic method,
3592 via callback functions, instead of by modifying libpng functions. This
3593 is illustrated in pngtest.c, which uses a callback function to handle a
3594 private "vpAg" chunk and the new "sTER" chunk, which are both unknown to
3597 If you wish to write your own transformation for the data, look through
3598 the part of the code that does the transformations, and check out some of
3599 the simpler ones to get an idea of how they work. Try to find a similar
3600 transformation to the one you want to add and copy off of it. More details
3601 can be found in the comments inside the code itself.
3603 Configuring for 16-bit platforms
3605 You will want to look into zconf.h to tell zlib (and thus libpng) that
3606 it cannot allocate more then 64K at a time. Even if you can, the memory
3607 won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K.
3611 For DOS users who only have access to the lower 640K, you will
3612 have to limit zlib's memory usage via a png_set_compression_mem_level()
3613 call. See zlib.h or zconf.h in the zlib library for more information.
3615 Configuring for Medium Model
3617 Libpng's support for medium model has been tested on most of the popular
3618 compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
3619 defined, and FAR gets defined to far in pngconf.h, and you should be
3620 all set. Everything in the library (except for zlib's structure) is
3621 expecting far data. You must use the typedefs with the p or pp on
3622 the end for pointers (or at least look at them and be careful). Make
3623 note that the rows of data are defined as png_bytepp, which is
3624 an "unsigned char far * far *".
3626 Configuring for gui/windowing platforms:
3628 You will need to write new error and warning functions that use the GUI
3629 interface, as described previously, and set them to be the error and
3630 warning functions at the time that png_create_*_struct() is called,
3631 in order to have them available during the structure initialization.
3632 They can be changed later via png_set_error_fn(). On some compilers,
3633 you may also have to change the memory allocators (png_malloc, etc.).
3635 Configuring for compiler xxx:
3637 All includes for libpng are in pngconf.h. If you need to add, change
3638 or delete an include, this is the place to do it.
3639 The includes that are not needed outside libpng are placed in pngpriv.h,
3640 which is only used by the routines inside libpng itself.
3641 The files in libpng proper only include pngpriv.h and png.h, which
3642 in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
3643 As of libpng-1.5.0, pngpriv.h also includes three other private header
3644 files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
3645 that previously appeared in the public headers.
3649 There are special functions to configure the compression. Perhaps the
3650 most useful one changes the compression level, which currently uses
3651 input compression values in the range 0 - 9. The library normally
3652 uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests
3653 have shown that for a large majority of images, compression values in
3654 the range 3-6 compress nearly as well as higher levels, and do so much
3655 faster. For online applications it may be desirable to have maximum speed
3656 (Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also
3657 specify no compression (Z_NO_COMPRESSION = 0), but this would create
3658 files larger than just storing the raw bitmap. You can specify the
3659 compression level by calling:
3662 png_set_compression_level(png_ptr, level);
3664 Another useful one is to reduce the memory level used by the library.
3665 The memory level defaults to 8, but it can be lowered if you are
3666 short on memory (running DOS, for example, where you only have 640K).
3667 Note that the memory level does have an effect on compression; among
3668 other things, lower levels will result in sections of incompressible
3669 data being emitted in smaller stored blocks, with a correspondingly
3670 larger relative overhead of up to 15% in the worst case.
3673 png_set_compression_mem_level(png_ptr, level);
3675 The other functions are for configuring zlib. They are not recommended
3676 for normal use and may result in writing an invalid PNG file. See
3677 zlib.h for more information on what these mean.
3680 png_set_compression_strategy(png_ptr,
3683 png_set_compression_window_bits(png_ptr,
3686 png_set_compression_method(png_ptr, method);
3688 png_set_compression_buffer_size(png_ptr, size);
3690 As of libpng version 1.5.4, additional APIs became
3691 available to set these separately for non-IDAT
3692 compressed chunks such as zTXt, iTXt, and iCCP:
3695 #if PNG_LIBPNG_VER >= 10504
3696 png_set_text_compression_level(png_ptr, level);
3698 png_set_text_compression_mem_level(png_ptr, level);
3700 png_set_text_compression_strategy(png_ptr,
3703 png_set_text_compression_window_bits(png_ptr,
3706 png_set_text_compression_method(png_ptr, method);
3709 Controlling row filtering
3711 If you want to control whether libpng uses filtering or not, which
3712 filters are used, and how it goes about picking row filters, you
3713 can call one of these functions. The selection and configuration
3714 of row filters can have a significant impact on the size and
3715 encoding speed and a somewhat lesser impact on the decoding speed
3716 of an image. Filtering is enabled by default for RGB and grayscale
3717 images (with and without alpha), but not for paletted images nor
3718 for any images with bit depths less than 8 bits/pixel.
3720 The 'method' parameter sets the main filtering method, which is
3721 currently only '0' in the PNG 1.2 specification. The 'filters'
3722 parameter sets which filter(s), if any, should be used for each
3723 scanline. Possible values are PNG_ALL_FILTERS and PNG_NO_FILTERS
3724 to turn filtering on and off, respectively.
3726 Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB,
3727 PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise
3728 ORed together with '|' to specify one or more filters to use.
3729 These filters are described in more detail in the PNG specification.
3730 If you intend to change the filter type during the course of writing
3731 the image, you should start with flags set for all of the filters
3732 you intend to use so that libpng can initialize its internal
3733 structures appropriately for all of the filter types. (Note that this
3734 means the first row must always be adaptively filtered, because libpng
3735 currently does not allocate the filter buffers until png_write_row()
3736 is called for the first time.)
3738 filters = PNG_FILTER_NONE | PNG_FILTER_SUB
3739 PNG_FILTER_UP | PNG_FILTER_AVG |
3740 PNG_FILTER_PAETH | PNG_ALL_FILTERS;
3742 png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE,
3744 The second parameter can also be
3745 PNG_INTRAPIXEL_DIFFERENCING if you are
3746 writing a PNG to be embedded in a MNG
3747 datastream. This parameter must be the
3748 same as the value of filter_method used
3751 It is also possible to influence how libpng chooses from among the
3752 available filters. This is done in one or both of two ways - by
3753 telling it how important it is to keep the same filter for successive
3754 rows, and by telling it the relative computational costs of the filters.
3756 double weights[3] = {1.5, 1.3, 1.1},
3757 costs[PNG_FILTER_VALUE_LAST] =
3758 {1.0, 1.3, 1.3, 1.5, 1.7};
3760 png_set_filter_heuristics(png_ptr,
3761 PNG_FILTER_HEURISTIC_WEIGHTED, 3,
3764 The weights are multiplying factors that indicate to libpng that the
3765 row filter should be the same for successive rows unless another row filter
3766 is that many times better than the previous filter. In the above example,
3767 if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a
3768 "sum of absolute differences" 1.5 x 1.3 times higher than other filters
3769 and still be chosen, while the NONE filter could have a sum 1.1 times
3770 higher than other filters and still be chosen. Unspecified weights are
3771 taken to be 1.0, and the specified weights should probably be declining
3772 like those above in order to emphasize recent filters over older filters.
3774 The filter costs specify for each filter type a relative decoding cost
3775 to be considered when selecting row filters. This means that filters
3776 with higher costs are less likely to be chosen over filters with lower
3777 costs, unless their "sum of absolute differences" is that much smaller.
3778 The costs do not necessarily reflect the exact computational speeds of
3779 the various filters, since this would unduly influence the final image
3782 Note that the numbers above were invented purely for this example and
3783 are given only to help explain the function usage. Little testing has
3784 been done to find optimum values for either the costs or the weights.
3786 Removing unwanted object code
3788 There are a bunch of #define's in pngconf.h that control what parts of
3789 libpng are compiled. All the defines end in _SUPPORTED. If you are
3790 never going to use a capability, you can change the #define to #undef
3791 before recompiling libpng and save yourself code and data space, or
3792 you can turn off individual capabilities with defines that begin with
3795 In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
3797 You can also turn all of the transforms and ancillary chunk capabilities
3798 off en masse with compiler directives that define
3799 PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
3801 along with directives to turn on any of the capabilities that you do
3802 want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra
3803 transformations but still leave the library fully capable of reading
3804 and writing PNG files with all known public chunks. Use of the
3805 PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
3806 that is incapable of reading or writing ancillary chunks. If you are
3807 not using the progressive reading capability, you can turn that off
3808 with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
3809 capability, which you'll still have).
3811 All the reading and writing specific code are in separate files, so the
3812 linker should only grab the files it needs. However, if you want to
3813 make sure, or if you are building a stand alone library, all the
3814 reading files start with "pngr" and all the writing files start with "pngw".
3815 The files that don't match either (like png.c, pngtrans.c, etc.)
3816 are used for both reading and writing, and always need to be included.
3817 The progressive reader is in pngpread.c
3819 If you are creating or distributing a dynamically linked library (a .so
3820 or DLL file), you should not remove or disable any parts of the library,
3821 as this will cause applications linked with different versions of the
3822 library to fail if they call functions not available in your library.
3823 The size of the library itself should not be an issue, because only
3824 those sections that are actually used will be loaded into memory.
3826 Requesting debug printout
3828 The macro definition PNG_DEBUG can be used to request debugging
3829 printout. Set it to an integer value in the range 0 to 3. Higher
3830 numbers result in increasing amounts of debugging information. The
3831 information is printed to the "stderr" file, unless another file
3832 name is specified in the PNG_DEBUG_FILE macro definition.
3834 When PNG_DEBUG > 0, the following functions (macros) become available:
3836 png_debug(level, message)
3837 png_debug1(level, message, p1)
3838 png_debug2(level, message, p1, p2)
3840 in which "level" is compared to PNG_DEBUG to decide whether to print
3841 the message, "message" is the formatted string to be printed,
3842 and p1 and p2 are parameters that are to be embedded in the string
3843 according to printf-style formatting directives. For example,
3845 png_debug1(2, "foo=%d\n", foo);
3850 fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo);
3852 When PNG_DEBUG is defined but is zero, the macros aren't defined, but you
3853 can still use PNG_DEBUG to control your own debugging:
3859 When PNG_DEBUG = 1, the macros are defined, but only png_debug statements
3860 having level = 0 will be printed. There aren't any such statements in
3861 this version of libpng, but if you insert some they will be printed.
3865 The MNG specification (available at http://www.libpng.org/pub/mng) allows
3866 certain extensions to PNG for PNG images that are embedded in MNG datastreams.
3867 Libpng can support some of these extensions. To enable them, use the
3868 png_permit_mng_features() function:
3870 feature_set = png_permit_mng_features(png_ptr, mask)
3872 mask is a png_uint_32 containing the bitwise OR of the
3873 features you want to enable. These include
3874 PNG_FLAG_MNG_EMPTY_PLTE
3875 PNG_FLAG_MNG_FILTER_64
3876 PNG_ALL_MNG_FEATURES
3878 feature_set is a png_uint_32 that is the bitwise AND of
3879 your mask with the set of MNG features that is
3880 supported by the version of libpng that you are using.
3882 It is an error to use this function when reading or writing a standalone
3883 PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped
3884 in a MNG datastream. As a minimum, it must have the MNG 8-byte signature
3885 and the MHDR and MEND chunks. Libpng does not provide support for these
3886 or any other MNG chunks; your application must provide its own support for
3887 them. You may wish to consider using libmng (available at
3888 http://www.libmng.com) instead.
3890 VII. Changes to Libpng from version 0.88
3892 It should be noted that versions of libpng later than 0.96 are not
3893 distributed by the original libpng author, Guy Schalnat, nor by
3894 Andreas Dilger, who had taken over from Guy during 1996 and 1997, and
3895 distributed versions 0.89 through 0.96, but rather by another member
3896 of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are
3897 still alive and well, but they have moved on to other things.
3899 The old libpng functions png_read_init(), png_write_init(),
3900 png_info_init(), png_read_destroy(), and png_write_destroy() have been
3901 moved to PNG_INTERNAL in version 0.95 to discourage their use. These
3902 functions will be removed from libpng version 1.4.0.
3904 The preferred method of creating and initializing the libpng structures is
3905 via the png_create_read_struct(), png_create_write_struct(), and
3906 png_create_info_struct() because they isolate the size of the structures
3907 from the application, allow version error checking, and also allow the
3908 use of custom error handling routines during the initialization, which
3909 the old functions do not. The functions png_read_destroy() and
3910 png_write_destroy() do not actually free the memory that libpng
3911 allocated for these structs, but just reset the data structures, so they
3912 can be used instead of png_destroy_read_struct() and
3913 png_destroy_write_struct() if you feel there is too much system overhead
3914 allocating and freeing the png_struct for each image read.
3916 Setting the error callbacks via png_set_message_fn() before
3917 png_read_init() as was suggested in libpng-0.88 is no longer supported
3918 because this caused applications that do not use custom error functions
3919 to fail if the png_ptr was not initialized to zero. It is still possible
3920 to set the error callbacks AFTER png_read_init(), or to change them with
3921 png_set_error_fn(), which is essentially the same function, but with a new
3922 name to force compilation errors with applications that try to use the old
3925 Starting with version 1.0.7, you can find out which version of the library
3926 you are using at run-time:
3928 png_uint_32 libpng_vn = png_access_version_number();
3930 The number libpng_vn is constructed from the major version, minor
3931 version with leading zero, and release number with leading zero,
3932 (e.g., libpng_vn for version 1.0.7 is 10007).
3934 Note that this function does not take a png_ptr, so you can call it
3935 before you've created one.
3937 You can also check which version of png.h you used when compiling your
3940 png_uint_32 application_vn = PNG_LIBPNG_VER;
3942 VIII. Changes to Libpng from version 1.0.x to 1.2.x
3944 Support for user memory management was enabled by default. To
3945 accomplish this, the functions png_create_read_struct_2(),
3946 png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(),
3947 png_malloc_default(), and png_free_default() were added.
3949 Support for the iTXt chunk has been enabled by default as of
3952 Support for certain MNG features was enabled.
3954 Support for numbered error messages was added. However, we never got
3955 around to actually numbering the error messages. The function
3956 png_set_strip_error_numbers() was added (Note: the prototype for this
3957 function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE
3958 builds of libpng-1.2.15. It was restored in libpng-1.2.36).
3960 The png_malloc_warn() function was added at libpng-1.2.3. This issues
3961 a png_warning and returns NULL instead of aborting when it fails to
3962 acquire the requested memory allocation.
3964 Support for setting user limits on image width and height was enabled
3965 by default. The functions png_set_user_limits(), png_get_user_width_max(),
3966 and png_get_user_height_max() were added at libpng-1.2.6.
3968 The png_set_add_alpha() function was added at libpng-1.2.7.
3970 The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9.
3971 Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the
3972 tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is
3975 A number of macro definitions in support of runtime selection of
3976 assembler code features (especially Intel MMX code support) were
3977 added at libpng-1.2.0:
3979 PNG_ASM_FLAG_MMX_SUPPORT_COMPILED
3980 PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU
3981 PNG_ASM_FLAG_MMX_READ_COMBINE_ROW
3982 PNG_ASM_FLAG_MMX_READ_INTERLACE
3983 PNG_ASM_FLAG_MMX_READ_FILTER_SUB
3984 PNG_ASM_FLAG_MMX_READ_FILTER_UP
3985 PNG_ASM_FLAG_MMX_READ_FILTER_AVG
3986 PNG_ASM_FLAG_MMX_READ_FILTER_PAETH
3987 PNG_ASM_FLAGS_INITIALIZED
3993 We added the following functions in support of runtime
3994 selection of assembler code features:
3996 png_get_mmx_flagmask()
3997 png_set_mmx_thresholds()
3999 png_get_mmx_bitdepth_threshold()
4000 png_get_mmx_rowbytes_threshold()
4003 We replaced all of these functions with simple stubs in libpng-1.2.20,
4004 when the Intel assembler code was removed due to a licensing issue.
4006 These macros are deprecated:
4008 PNG_READ_TRANSFORMS_NOT_SUPPORTED
4009 PNG_PROGRESSIVE_READ_NOT_SUPPORTED
4010 PNG_NO_SEQUENTIAL_READ_SUPPORTED
4011 PNG_WRITE_TRANSFORMS_NOT_SUPPORTED
4012 PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED
4013 PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED
4015 They have been replaced, respectively, by:
4017 PNG_NO_READ_TRANSFORMS
4018 PNG_NO_PROGRESSIVE_READ
4019 PNG_NO_SEQUENTIAL_READ
4020 PNG_NO_WRITE_TRANSFORMS
4021 PNG_NO_READ_ANCILLARY_CHUNKS
4022 PNG_NO_WRITE_ANCILLARY_CHUNKS
4024 PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been
4025 deprecated since libpng-1.0.16 and libpng-1.2.6.
4028 png_check_sig(sig, num)
4030 !png_sig_cmp(sig, 0, num)
4031 It has been deprecated since libpng-0.90.
4034 png_set_gray_1_2_4_to_8()
4035 which also expands tRNS to alpha was replaced with
4036 png_set_expand_gray_1_2_4_to_8()
4037 which does not. It has been deprecated since libpng-1.0.18 and 1.2.9.
4039 IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x
4041 Private libpng prototypes and macro definitions were moved from
4042 png.h and pngconf.h into a new pngpriv.h header file.
4044 Functions png_set_benign_errors(), png_benign_error(), and
4045 png_chunk_benign_error() were added.
4047 Support for setting the maximum amount of memory that the application
4048 will allocate for reading chunks was added, as a security measure.
4049 The functions png_set_chunk_cache_max() and png_get_chunk_cache_max()
4050 were added to the library.
4052 We implemented support for I/O states by adding png_ptr member io_state
4053 and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c
4055 We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level
4058 Checking for and reporting of errors in the IHDR chunk is more thorough.
4060 Support for global arrays was removed, to improve thread safety.
4062 Some obsolete/deprecated macros and functions have been removed.
4064 Typecasted NULL definitions such as
4065 #define png_voidp_NULL (png_voidp)NULL
4066 were eliminated. If you used these in your application, just use
4069 The png_struct and info_struct members "trans" and "trans_values" were
4070 changed to "trans_alpha" and "trans_color", respectively.
4072 The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles
4075 The PNG_1_0_X and PNG_1_2_X macros were eliminated.
4077 The PNG_LEGACY_SUPPORTED macro was eliminated.
4079 Many WIN32_WCE #ifdefs were removed.
4081 The functions png_read_init(info_ptr), png_write_init(info_ptr),
4082 png_info_init(info_ptr), png_read_destroy(), and png_write_destroy()
4083 have been removed. They have been deprecated since libpng-0.95.
4085 The png_permit_empty_plte() was removed. It has been deprecated
4086 since libpng-1.0.9. Use png_permit_mng_features() instead.
4088 We removed the obsolete stub functions png_get_mmx_flagmask(),
4089 png_set_mmx_thresholds(), png_get_asm_flags(),
4090 png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(),
4091 png_set_asm_flags(), and png_mmx_supported()
4093 We removed the obsolete png_check_sig(), png_memcpy_check(), and
4094 png_memset_check() functions. Instead use !png_sig_cmp(), png_memcpy(),
4095 and png_memset(), respectively.
4097 The function png_set_gray_1_2_4_to_8() was removed. It has been
4098 deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with
4099 png_set_expand_gray_1_2_4_to_8() because the former function also
4100 expanded any tRNS chunk to an alpha channel.
4102 Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32
4103 were added and are used by default instead of the corresponding
4104 functions. Unfortunately,
4105 from libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
4106 function) incorrectly returned a value of type png_uint_32.
4108 We changed the prototype for png_malloc() from
4109 png_malloc(png_structp png_ptr, png_uint_32 size)
4111 png_malloc(png_structp png_ptr, png_alloc_size_t size)
4113 This also applies to the prototype for the user replacement malloc_fn().
4115 The png_calloc() function was added and is used in place of
4116 of "png_malloc(); memset();" except in the case in png_read_png()
4117 where the array consists of pointers; in this case a "for" loop is used
4118 after the png_malloc() to set the pointers to NULL, to give robust.
4119 behavior in case the application runs out of memory part-way through
4122 We changed the prototypes of png_get_compression_buffer_size() and
4123 png_set_compression_buffer_size() to work with png_size_t instead of
4126 Support for numbered error messages was removed by default, since we
4127 never got around to actually numbering the error messages. The function
4128 png_set_strip_error_numbers() was removed from the library by default.
4130 The png_zalloc() and png_zfree() functions are no longer exported.
4131 The png_zalloc() function no longer zeroes out the memory that it
4132 allocates. Applications that called png_zalloc(png_ptr, number, size)
4133 can call png_calloc(png_ptr, number*size) instead, and can call
4134 png_free() instead of png_zfree().
4136 Support for dithering was disabled by default in libpng-1.4.0, because
4137 it has not been well tested and doesn't actually "dither".
4139 removed, however, and could be enabled by building libpng with
4140 PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support
4141 was reenabled, but the function was renamed png_set_quantize() to
4142 reflect more accurately what it actually does. At the same time,
4143 the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to
4144 PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED
4145 was renamed to PNG_READ_QUANTIZE_SUPPORTED.
4147 We removed the trailing '.' from the warning and error messages.
4149 X. Changes to Libpng from version 1.4.x to 1.5.x
4151 From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
4152 function) incorrectly returned a value of type png_uint_32.
4154 Checking for invalid palette index on read or write was added at libpng
4155 1.5.10. When an invalid index is found, libpng issues a benign error.
4156 This is enabled by default but can be disabled in each png_ptr with
4158 png_set_check_for_invalid_index(png_ptr, allowed);
4164 A. Changes that affect users of libpng
4166 There are no substantial API changes between the non-deprecated parts of
4167 the 1.4.5 API and the 1.5.0 API; however, the ability to directly access
4168 members of the main libpng control structures, png_struct and png_info,
4169 deprecated in earlier versions of libpng, has been completely removed from
4172 We no longer include zlib.h in png.h. Applications that need access
4173 to information in zlib.h will need to add the '#include "zlib.h"'
4174 directive. It does not matter whether it is placed prior to or after
4175 the '"#include png.h"' directive.
4177 The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used
4180 We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp()
4181 macros into a private header file (pngpriv.h) that is not accessible to
4184 In png_get_iCCP, the type of "profile" was changed from png_charpp
4185 to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep.
4187 There are changes of form in png.h, including new and changed macros to
4188 declare parts of the API. Some API functions with arguments that are
4189 pointers to data not modified within the function have been corrected to
4190 declare these arguments with PNG_CONST.
4192 Much of the internal use of C macros to control the library build has also
4193 changed and some of this is visible in the exported header files, in
4194 particular the use of macros to control data and API elements visible
4195 during application compilation may require significant revision to
4196 application code. (It is extremely rare for an application to do this.)
4198 Any program that compiled against libpng 1.4 and did not use deprecated
4199 features or access internal library structures should compile and work
4200 against libpng 1.5, except for the change in the prototype for
4201 png_get_iCCP() and png_set_iCCP() API functions mentioned above.
4203 libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of
4204 interlaced images. The macros return the number of rows and columns in
4205 each pass and information that can be used to de-interlace and (if
4206 absolutely necessary) interlace an image.
4208 libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls
4209 the application-provided png_longjmp_ptr on the internal, but application
4210 initialized, longjmp buffer. It is provided as a convenience to avoid
4211 the need to use the png_jmpbuf macro, which had the unnecessary side
4212 effect of resetting the internal png_longjmp_ptr value.
4214 libpng 1.5.0 includes a complete fixed point API. By default this is
4215 present along with the corresponding floating point API. In general the
4216 fixed point API is faster and smaller than the floating point one because
4217 the PNG file format used fixed point, not floating point. This applies
4218 even if the library uses floating point in internal calculations. A new
4219 macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library
4220 uses floating point arithmetic (the default) or fixed point arithmetic
4221 internally for performance critical calculations such as gamma correction.
4222 In some cases, the gamma calculations may produce slightly different
4223 results. This has changed the results in png_rgb_to_gray and in alpha
4224 composition (png_set_background for example). This applies even if the
4225 original image was already linear (gamma == 1.0) and, therefore, it is
4226 not necessary to linearize the image. This is because libpng has *not*
4227 been changed to optimize that case correctly, yet.
4229 Fixed point support for the sCAL chunk comes with an important caveat;
4230 the sCAL specification uses a decimal encoding of floating point values
4231 and the accuracy of PNG fixed point values is insufficient for
4232 representation of these values. Consequently a "string" API
4233 (png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading
4234 arbitrary sCAL chunks in the absence of either the floating point API or
4235 internal floating point calculations.
4237 Applications no longer need to include the optional distribution header
4238 file pngusr.h or define the corresponding macros during application
4239 build in order to see the correct variant of the libpng API. From 1.5.0
4240 application code can check for the corresponding _SUPPORTED macro:
4242 #ifdef PNG_INCH_CONVERSIONS_SUPPORTED
4243 /* code that uses the inch conversion APIs. */
4246 This macro will only be defined if the inch conversion functions have been
4247 compiled into libpng. The full set of macros, and whether or not support
4248 has been compiled in, are available in the header file pnglibconf.h.
4249 This header file is specific to the libpng build. Notice that prior to
4250 1.5.0 the _SUPPORTED macros would always have the default definition unless
4251 reset by pngusr.h or by explicit settings on the compiler command line.
4252 These settings may produce compiler warnings or errors in 1.5.0 because
4253 of macro redefinition.
4255 From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the
4256 function) incorrectly returned a value of type png_uint_32. libpng 1.5.0
4257 is consistent with the implementation in 1.4.5 and 1.2.x (where the macro
4260 Applications can now choose whether to use these macros or to call the
4261 corresponding function by defining PNG_USE_READ_MACROS or
4262 PNG_NO_USE_READ_MACROS before including png.h. Notice that this is
4263 only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0
4264 will lead to a link failure.
4266 Prior to libpng-1.5.4, the zlib compressor used the same set of parameters
4267 when compressing the IDAT data and textual data such as zTXt and iCCP.
4268 In libpng-1.5.4 we reinitialized the zlib stream for each type of data.
4269 We added five png_set_text_*() functions for setting the parameters to
4270 use with textual data.
4272 Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED
4273 option was off by default, and slightly inaccurate scaling occurred.
4274 This option can no longer be turned off, and the choice of accurate
4275 or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8()
4276 API for accurate scaling or the old png_set_strip_16_to_8() API for simple
4279 Prior to libpng-1.5.4, the png_set_user_limits() function could only be
4280 used to reduce the width and height limits from the value of
4281 PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said
4282 that it could be used to override them. Now this function will reduce or
4283 increase the limits.
4285 Starting in libpng-1.5.10, the user limits can be set en masse with the
4286 configuration option PNG_SAFE_LIMITS_SUPPORTED. If this option is enabled,
4287 a set of "safe" limits is applied in pngpriv.h. These can be overridden by
4288 application calls to png_set_user_limits(), png_set_user_chunk_cache_max(),
4289 and/or png_set_user_malloc_max() that increase or decrease the limits. Also,
4290 in libpng-1.5.10 the default width and height limits were increased
4291 from 1,000,000 to 0x7ffffff (i.e., made unlimited). Therefore, the
4294 png_user_width_max 0x7fffffff 1,000,000
4295 png_user_height_max 0x7fffffff 1,000,000
4296 png_user_chunk_cache_max 0 (unlimited) 128
4297 png_user_chunk_malloc_max 0 (unlimited) 8,000,000
4299 B. Changes to the build and configuration of libpng
4301 Details of internal changes to the library code can be found in the CHANGES
4302 file and in the GIT repository logs. These will be of no concern to the vast
4303 majority of library users or builders; however, the few who configure libpng
4304 to a non-default feature set may need to change how this is done.
4306 There should be no need for library builders to alter build scripts if
4307 these use the distributed build support - configure or the makefiles -
4308 however, users of the makefiles may care to update their build scripts
4309 to build pnglibconf.h where the corresponding makefile does not do so.
4311 Building libpng with a non-default configuration has changed completely.
4312 The old method using pngusr.h should still work correctly even though the
4313 way pngusr.h is used in the build has been changed; however, library
4314 builders will probably want to examine the changes to take advantage of
4315 new capabilities and to simplify their build system.
4317 B.1 Specific changes to library configuration capabilities
4319 The library now supports a complete fixed point implementation and can
4320 thus be used on systems that have no floating point support or very
4321 limited or slow support. Previously gamma correction, an essential part
4322 of complete PNG support, required reasonably fast floating point.
4324 As part of this the choice of internal implementation has been made
4325 independent of the choice of fixed versus floating point APIs and all the
4326 missing fixed point APIs have been implemented.
4328 The exact mechanism used to control attributes of API functions has
4329 changed. A single set of operating system independent macro definitions
4330 is used and operating system specific directives are defined in
4333 As part of this the mechanism used to choose procedure call standards on
4334 those systems that allow a choice has been changed. At present this only
4335 affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
4336 running on Intel processors. As before, PNGAPI is defined where required
4337 to control the exported API functions; however, two new macros, PNGCBAPI
4338 and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
4339 (PNGCAPI) for functions that must match a C library prototype (currently
4340 only png_longjmp_ptr, which must match the C longjmp function.) The new
4341 approach is documented in pngconf.h
4343 Despite these changes, libpng 1.5.0 only supports the native C function
4344 calling standard on those platforms tested so far (__cdecl on Microsoft
4345 Windows). This is because the support requirements for alternative
4346 calling conventions seem to no longer exist. Developers who find it
4347 necessary to set PNG_API_RULE to 1 should advise the mailing list
4348 (png-mng-implement) of this and library builders who use Openwatcom and
4349 therefore set PNG_API_RULE to 2 should also contact the mailing list.
4351 A new test program, pngvalid, is provided in addition to pngtest.
4352 pngvalid validates the arithmetic accuracy of the gamma correction
4353 calculations and includes a number of validations of the file format.
4354 A subset of the full range of tests is run when "make check" is done
4355 (in the 'configure' build.) pngvalid also allows total allocated memory
4356 usage to be evaluated and performs additional memory overwrite validation.
4358 Many changes to individual feature macros have been made. The following
4359 are the changes most likely to be noticed by library builders who
4362 1) All feature macros now have consistent naming:
4364 #define PNG_NO_feature turns the feature off
4365 #define PNG_feature_SUPPORTED turns the feature on
4367 pnglibconf.h contains one line for each feature macro which is either:
4369 #define PNG_feature_SUPPORTED
4371 if the feature is supported or:
4373 /*#undef PNG_feature_SUPPORTED*/
4375 if it is not. Library code consistently checks for the 'SUPPORTED' macro.
4376 It does not, and libpng applications should not, check for the 'NO' macro
4377 which will not normally be defined even if the feature is not supported.
4378 The 'NO' macros are only used internally for setting or not setting the
4379 corresponding 'SUPPORTED' macros.
4381 Compatibility with the old names is provided as follows:
4383 PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
4385 And the following definitions disable the corresponding feature:
4387 PNG_SETJMP_NOT_SUPPORTED disables SETJMP
4388 PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
4389 PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
4390 PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
4391 PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
4392 PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
4394 Library builders should remove use of the above, inconsistent, names.
4396 2) Warning and error message formatting was previously conditional on
4397 the STDIO feature. The library has been changed to use the
4398 CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
4399 the library no longer uses the printf(3) functions, even though the
4400 default read/write implementations use (FILE) style stdio.h functions.
4402 3) Three feature macros now control the fixed/floating point decisions:
4404 PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
4406 PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
4407 practice these are normally required internally anyway (because the PNG
4408 file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
4409 merely stops the function from being exported.
4411 PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
4412 point implementation or the fixed point one. Typically the fixed point
4413 implementation is larger and slower than the floating point implementation
4414 on a system that supports floating point; however, it may be faster on a
4415 system which lacks floating point hardware and therefore uses a software
4418 4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the
4419 functions to read and write ints to be disabled independently of
4420 PNG_USE_READ_MACROS, which allows libpng to be built with the functions
4421 even though the default is to use the macros - this allows applications
4422 to choose at app buildtime whether or not to use macros (previously
4423 impossible because the functions weren't in the default build.)
4425 B.2 Changes to the configuration mechanism
4427 Prior to libpng-1.5.0 library builders who needed to configure libpng
4428 had either to modify the exported pngconf.h header file to add system
4429 specific configuration or had to write feature selection macros into
4430 pngusr.h and cause this to be included into pngconf.h by defining
4431 PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
4432 application built without PNG_USER_CONFIG defined would see the
4433 unmodified, default, libpng API and thus would probably fail to link.
4435 These mechanisms still work in the configure build and in any makefile
4436 build that builds pnglibconf.h, although the feature selection macros
4437 have changed somewhat as described above. In 1.5.0, however, pngusr.h is
4438 processed only once, when the exported header file pnglibconf.h is built.
4439 pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
4440 build of pnglibconf.h and it is never included in an application build.
4442 The rarely used alternative of adding a list of feature macros to the
4443 CFLAGS setting in the build also still works; however, the macros will be
4444 copied to pnglibconf.h and this may produce macro redefinition warnings
4445 when the individual C files are compiled.
4447 All configuration now only works if pnglibconf.h is built from
4448 scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan
4449 (the original author of awk) maintains C source code of that awk and this
4450 and all known later implementations (often called by subtly different
4451 names - nawk and gawk for example) are adequate to build pnglibconf.h.
4452 The Sun Microsystems (now Oracle) program 'awk' is an earlier version
4453 and does not work; this may also apply to other systems that have a
4454 functioning awk called 'nawk'.
4456 Configuration options are now documented in scripts/pnglibconf.dfa. This
4457 file also includes dependency information that ensures a configuration is
4458 consistent; that is, if a feature is switched off dependent features are
4459 also removed. As a recommended alternative to using feature macros in
4460 pngusr.h a system builder may also define equivalent options in pngusr.dfa
4461 (or, indeed, any file) and add that to the configuration by setting
4462 DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate
4463 how to do this, and a case where pngusr.h is still required.
4465 XI. Detecting libpng
4467 The png_get_io_ptr() function has been present since libpng-0.88, has never
4468 changed, and is unaffected by conditional compilation macros. It is the
4469 best choice for use in configure scripts for detecting the presence of any
4470 libpng version since 0.88. In an autoconf "configure.in" you could use
4472 AC_CHECK_LIB(png, png_get_io_ptr, ...
4474 XII. Source code repository
4476 Since about February 2009, version 1.2.34, libpng has been under "git" source
4477 control. The git repository was built from old libpng-x.y.z.tar.gz files
4478 going back to version 0.70. You can access the git repository (read only)
4481 git://libpng.git.sourceforge.net/gitroot/libpng
4483 or you can browse it via "gitweb" at
4485 http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng
4487 Patches can be sent to glennrp at users.sourceforge.net or to
4488 png-mng-implement at lists.sourceforge.net or you can upload them to
4489 the libpng bug tracker at
4491 http://libpng.sourceforge.net
4493 We also accept patches built from the tar or zip distributions, and
4494 simple verbal discriptions of bug fixes, reported either to the
4495 SourceForge bug tracker, to the png-mng-implement at lists.sf.net
4496 mailing list, or directly to glennrp.
4500 Our coding style is similar to the "Allman" style, with curly
4501 braces on separate lines:
4508 else if (another condition)
4513 The braces can be omitted from simple one-line actions:
4518 We use 3-space indentation, except for continued statements which
4519 are usually indented the same as the first line of the statement
4520 plus four more spaces.
4522 For macro definitions we use 2-space indentation, always leaving the "#"
4523 in the first column.
4525 #ifndef PNG_NO_FEATURE
4526 # ifndef PNG_FEATURE_SUPPORTED
4527 # define PNG_FEATURE_SUPPORTED
4531 Comments appear with the leading "/*" at the same indentation as
4532 the statement that follows the comment:
4534 /* Single-line comment */
4537 /* This is a multiple-line
4542 Very short comments can be placed after the end of the statement
4543 to which they pertain:
4545 statement; /* comment */
4547 We don't use C++ style ("//") comments. We have, however,
4548 used them in the past in some now-abandoned MMX assembler
4551 Functions and their curly braces are not indented, and
4552 exported functions are marked with PNGAPI:
4554 /* This is a public function that is visible to
4555 * application programmers. It does thus-and-so.
4558 png_exported_function(png_ptr, png_info, foo)
4563 The prototypes for all exported functions appear in png.h,
4564 above the comment that says
4566 /* Maintainer: Put new public prototypes here ... */
4568 We mark all non-exported functions with "/* PRIVATE */"":
4571 png_non_exported_function(png_ptr, png_info, foo)
4576 The prototypes for non-exported functions (except for those in
4579 above the comment that says
4581 /* Maintainer: Put new private prototypes here ^ */
4583 To avoid polluting the global namespace, the names of all exported
4584 functions and variables begin with "png_", and all publicly visible C
4585 preprocessor macros begin with "PNG". We request that applications that
4586 use libpng *not* begin any of their own symbols with either of these strings.
4588 We put a space after each comma and after each semicolon
4589 in "for" statements, and we put spaces before and after each
4590 C binary operator and after "for" or "while", and before
4591 "?". We don't put a space between a typecast and the expression
4592 being cast, nor do we put one between a function name and the
4593 left parenthesis that follows it:
4595 for (i = 2; i > 0; --i)
4596 y[i] = a(x) + (int)b;
4598 We prefer #ifdef and #ifndef to #if defined() and #if !defined()
4599 when there is only one macro being tested.
4601 We prefer to express integers that are used as bit masks in hex format,
4602 with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100).
4604 We do not use the TAB character for indentation in the C sources.
4606 Lines do not exceed 80 characters.
4608 Other rules can be inferred by inspecting the libpng source.
4610 XIV. Y2K Compliance in libpng
4614 Since the PNG Development group is an ad-hoc body, we can't make
4615 an official declaration.
4617 This is your unofficial assurance that libpng from version 0.71 and
4618 upward through 1.5.14 are Y2K compliant. It is my belief that earlier
4619 versions were also Y2K compliant.
4621 Libpng only has two year fields. One is a 2-byte unsigned integer that
4622 will hold years up to 65535. The other holds the date in text
4623 format, and will hold years up to 9999.
4626 "png_uint_16 year" in png_time_struct.
4629 "char time_buffer[29]" in png_struct. This will no
4630 longer be used in libpng-1.6.x and will be removed from libpng-1.7.0.
4632 There are seven time-related functions:
4634 png_convert_to_rfc_1123() in png.c
4635 (formerly png_convert_to_rfc_1152() in error)
4636 png_convert_from_struct_tm() in pngwrite.c, called
4638 png_convert_from_time_t() in pngwrite.c
4639 png_get_tIME() in pngget.c
4640 png_handle_tIME() in pngrutil.c, called in pngread.c
4641 png_set_tIME() in pngset.c
4642 png_write_tIME() in pngwutil.c, called in pngwrite.c
4644 All appear to handle dates properly in a Y2K environment. The
4645 png_convert_from_time_t() function calls gmtime() to convert from system
4646 clock time, which returns (year - 1900), which we properly convert to
4647 the full 4-digit year. There is a possibility that applications using
4648 libpng are not passing 4-digit years into the png_convert_to_rfc_1123()
4649 function, or that they are incorrectly passing only a 2-digit year
4650 instead of "year - 1900" into the png_convert_from_struct_tm() function,
4651 but this is not under our control. The libpng documentation has always
4652 stated that it works with 4-digit years, and the APIs have been
4655 The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned
4656 integer to hold the year, and can hold years as large as 65535.
4658 zlib, upon which libpng depends, is also Y2K compliant. It contains
4659 no date-related code.
4662 Glenn Randers-Pehrson
4664 PNG Development Group