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