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