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