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