libpng.txt - A description on how to use and modify libpng libpng version 1.2.5 - October 3, 2002 Updated and distributed by Glenn Randers-Pehrson <randeg@alum.rpi.edu> Copyright (c) 1998-2002 Glenn Randers-Pehrson For conditions of distribution and use, see copyright notice in png.h. based on: libpng 1.0 beta 6  version 0.96 May 28, 1997 Updated and distributed by Andreas Dilger Copyright (c) 1996, 1997 Andreas Dilger libpng 1.0 beta 2 - version 0.88  January 26, 1996 For conditions of distribution and use, see copyright notice in png.h. Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. Updated/rewritten per request in the libpng FAQ Copyright (c) 1995, 1996 Frank J. T. Wojcik December 18, 1995 & January 20, 1996I. IntroductionThis file describes how to use and modify the PNG reference library(known as libpng) for your own use.  There are five sections to thisfile: introduction, structures, reading, writing, and modification andconfiguration notes for various special platforms.  In addition to thisfile, example.c is a good starting point for using the library, asit is heavily commented and should include everything most peoplewill need.  We assume that libpng is already installed; see theINSTALL file for instructions on how to install libpng.Libpng was written as a companion to the PNG specification, as a wayof reducing the amount of time and effort it takes to support the PNGfile format in application programs.The PNG-1.2 specification is available at <http://www.libpng.org/pub/png>and at <ftp://ftp.uu.net/graphics/png/documents/>.The PNG-1.0 specification is availableas RFC 2083 <ftp://ftp.uu.net/graphics/png/documents/> and as aW3C Recommendation <http://www.w3.org/TR/REC.png.html>. Someadditional chunks are described in the special-purpose public chunksdocuments at <ftp://ftp.uu.net/graphics/png/documents/>.Other informationabout PNG, and the latest version of libpng, can be found at the PNG homepage, <http://www.libpng.org/pub/png/>and at <ftp://ftp.uu.net/graphics/png/>.Most users will not have to modify the library significantly; advancedusers may want to modify it more.  All attempts were made to make it ascomplete as possible, while keeping the code easy to understand.Currently, this library only supports C.  Support for other languagesis being considered.Libpng has been designed to handle multiple sessions at one time,to be easily modifiable, to be portable to the vast majority ofmachines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easyto use.  The ultimate goal of libpng is to promote the acceptance ofthe PNG file format in whatever way possible.  While there is stillwork to be done (see the TODO file), libpng should cover themajority of the needs of its users.Libpng uses zlib for its compression and decompression of PNG files.Further information about zlib, and the latest version of zlib, canbe found at the zlib home page, <http://www.info-zip.org/pub/infozip/zlib/>.The zlib compression utility is a general purpose utility that isuseful for more than PNG files, and can be used without libpng.See the documentation delivered with zlib for more details.You can usually find the source files for the zlib utility wherever youfind the libpng source files.Libpng is thread safe, provided the threads are using differentinstances of the structures.  Each thread should have its ownpng_struct and png_info instances, and thus its own image.Libpng does not protect itself against two threads using thesame instance of a structure.  Note: thread safety may be defeatedby use of some of the MMX assembler code in pnggccrd.c, which is onlycompiled when the user defines PNG_THREAD_UNSAFE_OK.II. StructuresThere are two main structures that are important to libpng, png_structand png_info.  The first, png_struct, is an internal structure thatwill not, for the most part, be used by a user except as the firstvariable passed to every libpng function call.The png_info structure is designed to provide information about thePNG file.  At one time, the fields of png_info were intended to bedirectly accessible to the user.  However, this tended to cause problemswith applications using dynamically loaded libraries, and as a resulta set of interface functions for png_info (the png_get_*() and png_set_*()functions) was developed.  The fields of png_info are still available forolder applications, but it is suggested that applications use the newinterfaces if at all possible.Applications that do make direct access to the members of png_struct (exceptfor png_ptr->jmpbuf) must be recompiled whenever the library is updated,and applications that make direct access to the members of png_info mustbe recompiled if they were compiled or loaded with libpng version 1.0.6,in which the members were in a different order.  In version 1.0.7, themembers of the png_info structure reverted to the old order, as they werein versions 0.97c through 1.0.5.  Starting with version 2.0.0, bothstructures are going to be hidden, and the contents of the structures willonly be accessible through the png_get/png_set functions.The png.h header file is an invaluable reference for programming with libpng.And while I'm on the topic, make sure you include the libpng header file:#include <png.h>III. ReadingWe'll now walk you through the possible functions to call when readingin a PNG file sequentially, briefly explaining the syntax and purposeof each one.  See example.c and png.h for more detail.  Whileprogressive reading is covered in the next section, you will stillneed some of the functions discussed in this section to read a PNGfile.SetupYou will want to do the I/O initialization(*) before you get into libpng,so if it doesn't work, you don't have much to undo.  Of course, youwill also want to insure that you are, in fact, dealing with a PNGfile.  Libpng provides a simple check to see if a file is a PNG file.To use it, pass in the first 1 to 8 bytes of the file to the functionpng_sig_cmp(), and it will return 0 if the bytes match the correspondingbytes of the PNG signature, or nonzero otherwise.  Of course, the more bytesyou pass in, the greater the accuracy of the prediction.If you are intending to keep the file pointer open for use in libpng,you must ensure you don't read more than 8 bytes from the beginningof the file, and you also have to make a call to png_set_sig_bytes_read()with the number of bytes you read from the beginning.  Libpng willthen only check the bytes (if any) that your program didn't read.(*): If you are not using the standard I/O functions, you will needto replace them with custom functions.  See the discussion underCustomizing libpng.    FILE *fp = fopen(file_name, "rb");    if (!fp)    {        return (ERROR);    }    fread(header, 1, number, fp);    is_png = !png_sig_cmp(header, 0, number);    if (!is_png)    {        return (NOT_PNG);    }Next, png_struct and png_info need to be allocated and initialized.  Inorder to ensure that the size of these structures is correct even with adynamically linked libpng, there are functions to initialize andallocate the structures.  We also pass the library version, optionalpointers to error handling functions, and a pointer to a data struct foruse by the error functions, if necessary (the pointer and functions canbe NULL if the default error handlers are to be used).  See the sectionon Changes to Libpng below regarding the old initialization functions.The structure allocation functions quietly return NULL if they fail tocreate the structure, so your application should check for that.    png_structp png_ptr = png_create_read_struct       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,        user_error_fn, user_warning_fn);    if (!png_ptr)        return (ERROR);    png_infop info_ptr = png_create_info_struct(png_ptr);    if (!info_ptr)    {        png_destroy_read_struct(&png_ptr,           (png_infopp)NULL, (png_infopp)NULL);        return (ERROR);    }    png_infop end_info = png_create_info_struct(png_ptr);    if (!end_info)    {        png_destroy_read_struct(&png_ptr, &info_ptr,          (png_infopp)NULL);        return (ERROR);    }If you want to use your own memory allocation routines,define PNG_USER_MEM_SUPPORTED and usepng_create_read_struct_2() instead of png_create_read_struct():    png_structp png_ptr = png_create_read_struct_2       (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr,        user_error_fn, user_warning_fn, (png_voidp)        user_mem_ptr, user_malloc_fn, user_free_fn);The error handling routines passed to png_create_read_struct()and the memory alloc/free routines passed to png_create_struct_2()are only necessary if you are not using the libpng supplied errorhandling and memory alloc/free functions.When libpng encounters an error, it expects to longjmp backto your routine.  Therefore, you will need to call setjmp and passyour png_jmpbuf(png_ptr).  If you read the file from differentroutines, you will need to update the jmpbuf field every time you entera new routine that will call a png_*() function.See your documentation of setjmp/longjmp for your compiler for moreinformation on setjmp/longjmp.  See the discussion on libpng errorhandling in the Customizing Libpng section below for more informationon the libpng error handling.  If an error occurs, and libpng longjmp'sback to your setjmp, you will want to call png_destroy_read_struct() tofree any memory.    if (setjmp(png_jmpbuf(png_ptr)))    {        png_destroy_read_struct(&png_ptr, &info_ptr,           &end_info);        fclose(fp);        return (ERROR);    }If you would rather avoid the complexity of setjmp/longjmp issues,you can compile libpng with PNG_SETJMP_NOT_SUPPORTED, in which caseerrors will result in a call to PNG_ABORT() which defaults to abort().Now you need to set up the input code.  The default for libpng is touse the C function fread().  If you use this, you will need to pass avalid FILE * in the function png_init_io().  Be sure that the file isopened in binary mode.  If you wish to handle reading data in anotherway, you need not call the png_init_io() function, but you must thenimplement the libpng I/O methods discussed in the Customizing Libpngsection below.    png_init_io(png_ptr, fp);If you had previously opened the file and read any of the signature fromthe beginning in order to see if this was a PNG file, you need to letlibpng know that there are some bytes missing from the start of the file.    png_set_sig_bytes(png_ptr, number);Setting up callback codeYou can set up a callback function to handle any unknown chunks in theinput stream. You must supply the function    read_chunk_callback(png_ptr ptr,         png_unknown_chunkp chunk);    {       /* The unknown chunk structure contains your          chunk data: */           png_byte name[5];           png_byte *data;           png_size_t size;       /* Note that libpng has already taken care of          the CRC handling */       /* put your code here.  Return one of the          following: */       return (-n); /* chunk had an error */       return (0); /* did not recognize */       return (n); /* success */    }(You can give your function another name that you like instead of"read_chunk_callback")To inform libpng about your function, use    png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr,        read_chunk_callback);This names not only the callback function, but also a user pointer thatyou can retrieve with    png_get_user_chunk_ptr(png_ptr);At this point, you can set up a callback function that will becalled after each row has been read, which you can use to controla progress meter or the like.  It's demonstrated in pngtest.c.You must supply a function    void read_row_callback(png_ptr ptr, png_uint_32 row,       int pass);    {      /* put your code here */    }(You can give it another name that you like instead of "read_row_callback")To inform libpng about your function, use    png_set_read_status_fn(png_ptr, read_row_callback);Unknown-chunk handlingNow you get to set the way the library processes unknown chunks in theinput PNG stream. Both known and unknown chunks will be read.  Normalbehavior is that known chunks will be parsed into information invarious info_ptr members; unknown chunks will be discarded. To changethis, you can call:    png_set_keep_unknown_chunks(png_ptr, info_ptr, keep,        chunk_list, num_chunks);    keep       - 0: do not keep                 1: keep only if safe-to-copy                 2: keep even if unsafe-to-copy    chunk_list - list of chunks affected (a byte string,