diff options
Diffstat (limited to 'src/3rdparty/libpng/libpng-manual.txt')
| -rw-r--r-- | src/3rdparty/libpng/libpng-manual.txt | 1399 |
1 files changed, 1041 insertions, 358 deletions
diff --git a/src/3rdparty/libpng/libpng-manual.txt b/src/3rdparty/libpng/libpng-manual.txt index d55e80a009..f0dae987f9 100644 --- a/src/3rdparty/libpng/libpng-manual.txt +++ b/src/3rdparty/libpng/libpng-manual.txt @@ -1,9 +1,9 @@ libpng-manual.txt - A description on how to use and modify libpng - libpng version 1.5.10 - March 29, 2012 + libpng version 1.6.17 - March 26, 2015 Updated and distributed by Glenn Randers-Pehrson <glennrp at users.sourceforge.net> - Copyright (c) 1998-2011 Glenn Randers-Pehrson + Copyright (c) 1998-2015 Glenn Randers-Pehrson This document is released under the libpng license. For conditions of distribution and use, see the disclaimer @@ -11,15 +11,15 @@ libpng-manual.txt - A description on how to use and modify libpng Based on: - libpng versions 0.97, January 1998, through 1.5.10 - March 29, 2012 + libpng versions 0.97, January 1998, through 1.6.17 - March 26, 2015 Updated and distributed by Glenn Randers-Pehrson - Copyright (c) 1998-2011 Glenn Randers-Pehrson + Copyright (c) 1998-2015 Glenn Randers-Pehrson - libpng 1.0 beta 6 version 0.96 May 28, 1997 + 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 + 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. @@ -28,16 +28,33 @@ libpng-manual.txt - A description on how to use and modify libpng Copyright (c) 1995, 1996 Frank J. T. Wojcik December 18, 1995 & January 20, 1996 + TABLE OF CONTENTS + + I. Introduction + II. Structures + III. Reading + IV. Writing + V. Simplified API + VI. Modifying/Customizing libpng + VII. MNG support + VIII. Changes to Libpng from version 0.88 + IX. Changes to Libpng from version 1.0.x to 1.2.x + X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x + XI. Changes to Libpng from version 1.4.x to 1.5.x + XII. Changes to Libpng from version 1.5.x to 1.6.x + XIII. Detecting libpng + XIV. Source code repository + XV. Coding style + XVI. Y2K Compliance in libpng + I. Introduction This file describes how to use and modify the PNG reference library -(known as libpng) for your own use. There are five sections to this -file: introduction, structures, reading, writing, and modification and -configuration notes for various special platforms. In addition to this +(known as libpng) for your own use. In addition to this file, example.c is a good starting point for using the library, as it is heavily commented and should include everything most people will need. We assume that libpng is already installed; see the -INSTALL file for instructions on how to install libpng. +INSTALL file for instructions on how to configure and install libpng. For examples of libpng usage, see the files "example.c", "pngtest.c", and the files in the "contrib" directory, all of which are included in @@ -48,7 +65,7 @@ of reducing the amount of time and effort it takes to support the PNG file format in application programs. The PNG specification (second edition), November 2003, is available as -a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at +a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2004 (E)) at <http://www.w3.org/TR/2003/REC-PNG-20031110/ The W3C and ISO documents have identical technical content. @@ -141,8 +158,8 @@ APIs. Most of these are fairly obvious; for example types corresponding to integers of particular sizes and types for passing color values. One exception is how non-integral numbers are handled. For application -convenience most APIs that take such numbers have C (double) arguments, -however internally PNG, and libpng, use 32 bit signed integers and encode +convenience most APIs that take such numbers have C (double) arguments; +however, internally PNG, and libpng, use 32 bit signed integers and encode the value by multiplying by 100,000. As of libpng 1.5.0 a convenience macro PNG_FP_1 is defined in png.h along with a type (png_fixed_point) which is simply (png_int_32). @@ -257,10 +274,10 @@ This method of building a customized pnglibconf.h is illustrated in contrib/pngminim/*. See the "$(PNGCONF):" target in the makefile and pngusr.dfa in these directories. -C. Configuration using PNG_USR_CONFIG +C. Configuration using PNG_USER_CONFIG -If -DPNG_USR_CONFIG is added to the CFLAGS when pnglibconf.h is built the file -pngusr.h will automatically be included before the options in +If -DPNG_USER_CONFIG is added to the CPPFLAGS when pnglibconf.h is built, +the file pngusr.h will automatically be included before the options in scripts/pnglibconf.dfa are processed. Your pngusr.h file should contain only macro definitions turning features on or off or setting settings. @@ -319,7 +336,7 @@ 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 beginning -of the file, and you also have to make a call to png_set_sig_bytes_read() +of the file, and you also have to make a call to png_set_sig_bytes() with the number of bytes you read from the beginning. Libpng will then only check the bytes (if any) that your program didn't read. @@ -327,22 +344,23 @@ then only check the bytes (if any) that your program didn't read. to replace them with custom functions. See the discussion under Customizing 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 (fread(header, 1, number, fp) != number) + { + return (ERROR); + } + 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. In order to ensure that the size of these structures is correct even with a dynamically linked libpng, there are functions to initialize and @@ -508,9 +526,14 @@ you can retrieve with png_get_user_chunk_ptr(png_ptr); If you call the png_set_read_user_chunk_fn() function, then all unknown -chunks will be saved when read, in case your callback function will need -one or more of them. This behavior can be changed with the -png_set_keep_unknown_chunks() function, described below. +chunks which the callback does not handle will be saved when read. You can +cause them to be discarded by returning '1' ("handled") instead of '0'. This +behavior will change in libpng 1.7 and the default handling set by the +png_set_keep_unknown_chunks() function, described below, will be used when the +callback returns 0. If you want the existing behavior you should set the global +default to PNG_HANDLE_CHUNK_IF_SAFE now; this is compatible with all current +versions of libpng and with 1.7. Libpng 1.6 issues a warning if you keep the +default, or PNG_HANDLE_CHUNK_NEVER, and the callback returns 0. At this point, you can set up a callback function that will be called after each row has been read, which you can use to control @@ -553,6 +576,7 @@ chunk types. To change this, you can call: png_set_keep_unknown_chunks(png_ptr, keep, chunk_list, num_chunks); + keep - 0: default unknown chunk handling 1: ignore; do not keep 2: keep only if safe-to-copy @@ -566,11 +590,16 @@ chunk types. To change this, you can call: chunk_list - list of chunks affected (a byte string, five bytes per chunk, NULL or '\0' if - num_chunks is 0) + num_chunks is positive; ignored if + numchunks <= 0). num_chunks - number of chunks affected; if 0, all - unknown chunks are affected. If nonzero, - only the chunks in the list are affected + unknown chunks are affected. If positive, + only the chunks in the list are affected, + and if negative all unknown chunks and + all known chunks except for the IHDR, + PLTE, tRNS, IDAT, and IEND chunks are + affected. Unknown chunks declared in this way will be saved as raw data onto a list of png_unknown_chunk structures. If a chunk that is normally @@ -603,30 +632,29 @@ callback function: ... #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) - /* ignore all unknown chunks: */ - png_set_keep_unknown_chunks(read_ptr, 1, NULL, 0); + /* ignore all unknown chunks + * (use global setting "2" for libpng16 and earlier): + */ + png_set_keep_unknown_chunks(read_ptr, 2, NULL, 0); /* except for vpAg: */ png_set_keep_unknown_chunks(read_ptr, 2, vpAg, 1); /* also ignore unused known chunks: */ png_set_keep_unknown_chunks(read_ptr, 1, unused_chunks, - (int)sizeof(unused_chunks)/5); + (int)(sizeof unused_chunks)/5); #endif User limits The PNG specification allows the width and height of an image to be as large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns. -Since very few applications really need to process such large images, -we have imposed an arbitrary 1-million limit on rows and columns. Larger images will be rejected immediately with a png_error() call. If -you wish to change this limit, you can use +you wish to change these limits, you can use png_set_user_limits(png_ptr, width_max, height_max); -to set your own limits, or use width_max = height_max = 0x7fffffffL -to allow all valid dimensions (libpng may reject some very large images +to set your own limits (libpng may reject some very wide images anyway because of potential buffer overflow conditions). You should put this statement after you create the PNG structure and @@ -650,9 +678,6 @@ where 0x7fffffffL means unlimited. You can retrieve this limit with chunk_cache_max = png_get_chunk_cache_max(png_ptr); -This limit also applies to the number of buffers that can be allocated -by png_decompress_chunk() while decompressing iTXt, zTXt, and iCCP chunks. - You can also set a limit on the amount of memory that a compressed chunk other than IDAT can occupy, with @@ -685,11 +710,12 @@ value. You can also specify a default encoding for the PNG file in case the required information is missing from the file. By default libpng assumes that the PNG data matches your system, to keep this default call: - png_set_gamma(png_ptr, screen_gamma, 1/screen_gamma/*file gamma*/); + png_set_gamma(png_ptr, screen_gamma, output_gamma); or you can use the fixed point equivalent: - png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, PNG_FP_1/screen_gamma); + png_set_gamma_fixed(png_ptr, PNG_FP_1*screen_gamma, + PNG_FP_1*output_gamma); If you don't know the gamma for your system it is probably 2.2 - a good approximation to the IEC standard for display systems (sRGB). If images are @@ -701,19 +727,86 @@ display driver, a few systems, including older Macs, change the response by default. As of 1.5.4 three special values are available to handle common situations: - PNG_DEFAULT_sRGB: Indicates that the system conforms to the IEC 61966-2-1 - standard. This matches almost all systems. - PNG_GAMMA_MAC_18: Indicates that the system is an older (pre Mac OS 10.6) - Apple Macintosh system with the default settings. - PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates that the - system expects data with no gamma encoding. + PNG_DEFAULT_sRGB: Indicates that the system conforms to the + IEC 61966-2-1 standard. This matches almost + all systems. + PNG_GAMMA_MAC_18: Indicates that the system is an older + (pre Mac OS 10.6) Apple Macintosh system with + the default settings. + PNG_GAMMA_LINEAR: Just the fixed point value for 1.0 - indicates + that the system expects data with no gamma + encoding. You would use the linear (unencoded) value if you need to process the pixel -values further because this avoids the need to decode and reencode each +values further because this avoids the need to decode and re-encode each component value whenever arithmetic is performed. A lot of graphics software uses linear values for this reason, often with higher precision component values to preserve overall accuracy. + +The output_gamma value expresses how to decode the output values, not how +they are encoded. The values used correspond to the normal numbers used to +describe the overall gamma of a computer display system; for example 2.2 for +an sRGB conformant system. The values are scaled by 100000 in the _fixed +version of the API (so 220000 for sRGB.) + +The inverse of the value is always used to provide a default for the PNG file +encoding if it has no gAMA chunk and if png_set_gamma() has not been called +to override the PNG gamma information. + +When the ALPHA_OPTIMIZED mode is selected the output gamma is used to encode +opaque pixels however pixels with lower alpha values are not encoded, +regardless of the output gamma setting. + +When the standard Porter Duff handling is requested with mode 1 the output +encoding is set to be linear and the output_gamma value is only relevant +as a default for input data that has no gamma information. The linear output +encoding will be overridden if png_set_gamma() is called - the results may be +highly unexpected! + +The following numbers are derived from the sRGB standard and the research +behind it. sRGB is defined to be approximated by a PNG gAMA chunk value of +0.45455 (1/2.2) for PNG. The value implicitly includes any viewing +correction required to take account of any differences in the color +environment of the original scene and the intended display environment; the +value expresses how to *decode* the image for display, not how the original +data was *encoded*. + +sRGB provides a peg for the PNG standard by defining a viewing environment. +sRGB itself, and earlier TV standards, actually use a more complex transform +(a linear portion then a gamma 2.4 power law) than PNG can express. (PNG is +limited to simple power laws.) By saying that an image for direct display on +an sRGB conformant system should be stored with a gAMA chunk value of 45455 +(11.3.3.2 and 11.3.3.5 of the ISO PNG specification) the PNG specification +makes it possible to derive values for other display systems and +environments. + +The Mac value is deduced from the sRGB based on an assumption that the actual +extra viewing correction used in early Mac display systems was implemented as +a power 1.45 lookup table. + +Any system where a programmable lookup table is used or where the behavior of +the final display device characteristics can be changed requires system +specific code to obtain the current characteristic. However this can be +difficult and most PNG gamma correction only requires an approximate value. + +By default, if png_set_alpha_mode() is not called, libpng assumes that all +values are unencoded, linear, values and that the output device also has a +linear characteristic. This is only very rarely correct - it is invariably +better to call png_set_alpha_mode() with PNG_DEFAULT_sRGB than rely on the +default if you don't know what the right answer is! + +The special value PNG_GAMMA_MAC_18 indicates an older Mac system (pre Mac OS +10.6) which used a correction table to implement a somewhat lower gamma on an +otherwise sRGB system. + +Both these values are reserved (not simple gamma values) in order to allow +more precise correction internally in the future. + +NOTE: the values can be passed to either the fixed or floating +point APIs, but the floating point API will also accept floating point +values. + The second thing you may need to tell libpng about is how your system handles alpha channel information. Some, but not all, PNG files contain an alpha channel. To display these files correctly you need to compose the data onto a @@ -723,11 +816,11 @@ Libpng only supports composing onto a single color (using png_set_background; see below). Otherwise you must do the composition yourself and, in this case, you may need to call png_set_alpha_mode: -#if PNG_LIBPNG_VER >= 10504 - png_set_alpha_mode(png_ptr, mode, screen_gamma); -#else - png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma); -#endif + #if PNG_LIBPNG_VER >= 10504 + png_set_alpha_mode(png_ptr, mode, screen_gamma); + #else + png_set_gamma(png_ptr, screen_gamma, 1.0/screen_gamma); + #endif The screen_gamma value is the same as the argument to png_set_gamma; however, how it affects the output depends on the mode. png_set_alpha_mode() sets the @@ -738,11 +831,11 @@ by png_set_alpha_mode(). The mode is as follows: - PNG_ALPHA_PNG: The data is encoded according to the PNG specification. Red, -green and blue, or gray, components are gamma encoded color -values and are not premultiplied by the alpha value. The -alpha value is a linear measure of the contribution of the -pixel to the corresponding final output pixel. + PNG_ALPHA_PNG: The data is encoded according to the PNG +specification. Red, green and blue, or gray, components are +gamma encoded color values and are not premultiplied by the +alpha value. The alpha value is a linear measure of the +contribution of the pixel to the corresponding final output pixel. You should normally use this format if you intend to perform color correction on the color values; most, maybe all, color @@ -759,11 +852,35 @@ be used! The remaining modes assume you don't need to do any further color correction or that if you do, your color correction software knows all about alpha (it -probably doesn't!) - - PNG_ALPHA_STANDARD: The data libpng produces -is encoded in the standard way -assumed by most correctly written graphics software. +probably doesn't!). They 'associate' the alpha with the color information by +storing color channel values that have been scaled by the alpha. The +advantage is that the color channels can be resampled (the image can be +scaled) in this form. The disadvantage is that normal practice is to store +linear, not (gamma) encoded, values and this requires 16-bit channels for +still images rather than the 8-bit channels that are just about sufficient if +gamma encoding is used. In addition all non-transparent pixel values, +including completely opaque ones, must be gamma encoded to produce the final +image. These are the 'STANDARD', 'ASSOCIATED' or 'PREMULTIPLIED' modes +described below (the latter being the two common names for associated alpha +color channels). Note that PNG files always contain non-associated color +channels; png_set_alpha_mode() with one of the modes causes the decoder to +convert the pixels to an associated form before returning them to your +application. + +Since it is not necessary to perform arithmetic on opaque color values so +long as they are not to be resampled and are in the final color space it is +possible to optimize the handling of alpha by storing the opaque pixels in +the PNG format (adjusted for the output color space) while storing partially +opaque pixels in the standard, linear, format. The accuracy required for +standard alpha composition is relatively low, because the pixels are +isolated, therefore typically the accuracy loss in storing 8-bit linear +values is acceptable. (This is not true if the alpha channel is used to +simulate transparency over large areas - use 16 bits or the PNG mode in +this case!) This is the 'OPTIMIZED' mode. For this mode a pixel is +treated as opaque only if the alpha value is equal to the maximum value. + + PNG_ALPHA_STANDARD: The data libpng produces is encoded in the +standard way assumed by most correctly written graphics software. The gamma encoding will be removed by libpng and the linear component values will be pre-multiplied by the alpha channel. @@ -792,14 +909,13 @@ dynamic range. To avoid problems, and if your software supports it, use png_set_expand_16() to force all components to 16 bits. - PNG_ALPHA_OPTIMIZED: This mode is the same -as PNG_ALPHA_STANDARD except that -completely opaque pixels are gamma encoded according to + PNG_ALPHA_OPTIMIZED: This mode is the same as PNG_ALPHA_STANDARD +except that completely opaque pixels are gamma encoded according to the screen_gamma value. Pixels with alpha less than 1.0 will still have linear components. Use this format if you have control over your -compositing software and do don't do other arithmetic +compositing software and so don't do other arithmetic (such as scaling) on the data you get from libpng. Your compositing software can simply copy opaque pixels to the output but still has linear values for the @@ -813,18 +929,16 @@ representation of non-opaque pixels are irrelevant. You can also try this format if your software is broken; it might look better. - PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD; -however, all component values, -including the alpha channel are gamma encoded. This is -an appropriate format to try if your software, or more -likely hardware, is totally broken, i.e., if it performs -linear arithmetic directly on gamma encoded values. - -In most cases of broken software or hardware the bug in the final display -manifests as a subtle halo around composited parts of the image. You may not -even perceive this as a halo; the composited part of the image may simply appear -separate from the background, as though it had been cut out of paper and pasted -on afterward. + PNG_ALPHA_BROKEN: This is PNG_ALPHA_STANDARD; however, all component +values, including the alpha channel are gamma encoded. This is +broken because, in practice, no implementation that uses this choice +correctly undoes the encoding before handling alpha composition. Use this +choice only if other serious errors in the software or hardware you use +mandate it. In most cases of broken software or hardware the bug in the +final display manifests as a subtle halo around composited parts of the +image. You may not even perceive this as a halo; the composited part of +the image may simply appear separate from the background, as though it had +been cut out of paper and pasted on afterward. If you don't have to deal with bugs in software or hardware, or if you can fix them, there are three recommended ways of using png_set_alpha_mode(): @@ -855,6 +969,89 @@ All you can do is compose the result onto a matching output. Since this mode is libpng-specific you also need to write your own composition software. +The following are examples of calls to png_set_alpha_mode to achieve the +required overall gamma correction and, where necessary, alpha +premultiplication. + + png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB); + +This is the default libpng handling of the alpha channel - it is not +pre-multiplied into the color components. In addition the call states +that the output is for a sRGB system and causes all PNG files without gAMA +chunks to be assumed to be encoded using sRGB. + + png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC); + +In this case the output is assumed to be something like an sRGB conformant +display preceeded by a power-law lookup table of power 1.45. This is how +early Mac systems behaved. + + png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_GAMMA_LINEAR); + +This is the classic Jim Blinn approach and will work in academic +environments where everything is done by the book. It has the shortcoming +of assuming that input PNG data with no gamma information is linear - this +is unlikely to be correct unless the PNG files where generated locally. +Most of the time the output precision will be so low as to show +significant banding in dark areas of the image. + + png_set_expand_16(pp); + png_set_alpha_mode(pp, PNG_ALPHA_STANDARD, PNG_DEFAULT_sRGB); + +This is a somewhat more realistic Jim Blinn inspired approach. PNG files +are assumed to have the sRGB encoding if not marked with a gamma value and +the output is always 16 bits per component. This permits accurate scaling +and processing of the data. If you know that your input PNG files were +generated locally you might need to replace PNG_DEFAULT_sRGB with the +correct value for your system. + + png_set_alpha_mode(pp, PNG_ALPHA_OPTIMIZED, PNG_DEFAULT_sRGB); + +If you just need to composite the PNG image onto an existing background +and if you control the code that does this you can use the optimization +setting. In this case you just copy completely opaque pixels to the +output. For pixels that are not completely transparent (you just skip +those) you do the composition math using png_composite or png_composite_16 +below then encode the resultant 8-bit or 16-bit values to match the output +encoding. + + Other cases + +If neither the PNG nor the standard linear encoding work for you because +of the software or hardware you use then you have a big problem. The PNG +case will probably result in halos around the image. The linear encoding +will probably result in a washed out, too bright, image (it's actually too +contrasty.) Try the ALPHA_OPTIMIZED mode above - this will probably +substantially reduce the halos. Alternatively try: + + png_set_alpha_mode(pp, PNG_ALPHA_BROKEN, PNG_DEFAULT_sRGB); + +This option will also reduce the halos, but there will be slight dark +halos round the opaque parts of the image where the background is light. +In the OPTIMIZED mode the halos will be light halos where the background +is dark. Take your pick - the halos are unavoidable unless you can get +your hardware/software fixed! (The OPTIMIZED approach is slightly +faster.) + +When the default gamma of PNG files doesn't match the output gamma. +If you have PNG files with no gamma information png_set_alpha_mode allows +you to provide a default gamma, but it also sets the ouput gamma to the +matching value. If you know your PNG files have a gamma that doesn't +match the output you can take advantage of the fact that +png_set_alpha_mode always sets the output gamma but only sets the PNG +default if it is not already set: + + png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_DEFAULT_sRGB); + png_set_alpha_mode(pp, PNG_ALPHA_PNG, PNG_GAMMA_MAC); + +The first call sets both the default and the output gamma values, the +second call overrides the output gamma without changing the default. This +is easier than achieving the same effect with png_set_gamma. You must use +PNG_ALPHA_PNG for the first call - internal checking in png_set_alpha will +fire if more than one call to png_set_alpha_mode and png_set_background is +made in the same read operation, however multiple calls with PNG_ALPHA_PNG +are ignored. + If you don't need, or can't handle, the alpha channel you can call png_set_background() to remove it by compositing against a fixed color. Don't call png_set_strip_alpha() to do this - it will leave spurious pixel values in @@ -962,7 +1159,7 @@ where row_pointers is an array of pointers to the pixel data for each row: If you know your image size and pixel size ahead of time, you can allocate row_pointers prior to calling png_read_png() with - if (height > PNG_UINT_32_MAX/png_sizeof(png_byte)) + if (height > PNG_UINT_32_MAX/(sizeof (png_byte))) png_error (png_ptr, "Image is too tall to process in memory"); @@ -971,7 +1168,7 @@ row_pointers prior to calling png_read_png() with "Image is too wide to process in memory"); row_pointers = png_malloc(png_ptr, - height*png_sizeof(png_bytep)); + height*(sizeof (png_bytep))); for (int i=0; i<height, i++) row_pointers[i]=NULL; /* security precaution */ @@ -1068,13 +1265,13 @@ in until png_read_end() has read the chunk data following the image. the PNG datastream is embedded in a MNG-1.0 datastream) - Any or all of interlace_type, compression_type, or - filter_method can be NULL if you are - not interested in their values. + Any of width, height, color_type, bit_depth, + interlace_type, compression_type, or filter_method can + be NULL if you are not interested in their values. Note that png_get_IHDR() returns 32-bit data into the application's width and height variables. - This is an unsafe situation if these are 16-bit + This is an unsafe situation if these are not png_uint_32 variables. In such situations, the png_get_image_width() and png_get_image_height() functions described below are safer. @@ -1130,6 +1327,15 @@ data has been read, or zero if it is missing. The parameters to the png_get_<chunk> are set directly if they are simple data types, or a pointer into the info_ptr is returned for any complex types. +The colorspace data from gAMA, cHRM, sRGB, iCCP, and sBIT chunks +is simply returned to give the application information about how the +image was encoded. Libpng itself only does transformations using the file +gamma when combining semitransparent pixels with the background color, and, +since libpng-1.6.0, when converting between 8-bit sRGB and 16-bit linear pixels +within the simplified API. Libpng also uses the file gamma when converting +RGB to gray, beginning with libpng-1.0.5, if the application calls +png_set_rgb_to_gray()). + png_get_PLTE(png_ptr, info_ptr, &palette, &num_palette); @@ -1147,31 +1353,36 @@ pointer into the info_ptr is returned for any complex types. int_file_gamma - 100,000 times the gamma at which the file is written - png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x, &red_y, - &green_x, &green_y, &blue_x, &blue_y) - png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, &green_X, - &green_Y, &green_Z, &blue_X, &blue_Y, &blue_Z) - png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, &int_white_y, - &int_red_x, &int_red_y, &int_green_x, &int_green_y, - &int_blue_x, &int_blue_y) + png_get_cHRM(png_ptr, info_ptr, &white_x, &white_y, &red_x, + &red_y, &green_x, &green_y, &blue_x, &blue_y) + png_get_cHRM_XYZ(png_ptr, info_ptr, &red_X, &red_Y, &red_Z, + &green_X, &green_Y, &green_Z, &blue_X, &blue_Y, + &blue_Z) + png_get_cHRM_fixed(png_ptr, info_ptr, &int_white_x, + &int_white_y, &int_red_x, &int_red_y, + &int_green_x, &int_green_y, &int_blue_x, + &int_blue_y) png_get_cHRM_XYZ_fixed(png_ptr, info_ptr, &int_red_X, &int_red_Y, - &int_red_Z, &int_green_X, &int_green_Y, &int_green_Z, - &int_blue_X, &int_blue_Y, &int_blue_Z) + &int_red_Z, &int_green_X, &int_green_Y, + &int_green_Z, &int_blue_X, &int_blue_Y, + &int_blue_Z) {white,red,green,blue}_{x,y} - A color space encoding specified using the chromaticities - of the end points and the white point. (PNG_INFO_cHRM) + A color space encoding specified using the + chromaticities of the end points and the + white point. (PNG_INFO_cHRM) {red,green,blue}_{X,Y,Z} - A color space encoding specified using the encoding end - points - the CIE tristimulus specification of the intended - color of the red, green and blue channels in the PNG RGB - data. The white point is simply the sum of the three end - points. (PNG_INFO_cHRM) + A color space encoding specified using the + encoding end points - the CIE tristimulus + specification of the intended color of the red, + green and blue channels in the PNG RGB data. + The white point is simply the sum of the three + end points. (PNG_INFO_cHRM) png_get_sRGB(png_ptr, info_ptr, &srgb_intent); - file_srgb_intent - the rendering intent (PNG_INFO_sRGB) + srgb_intent - the rendering intent (PNG_INFO_sRGB) The presence of the sRGB chunk means that the pixel data is in the sRGB color space. This chunk also @@ -1571,17 +1782,19 @@ Within the matrix, "A" means the transformation is obtained by png_set_add_alpha(). "X" means the transformation is obtained by png_set_expand(). "1" means the transformation is obtained by - png_set_expand_gray_1_2_4_to_8() (and by png_set_expand() if there - is no transparency in the original or the final format). + png_set_expand_gray_1_2_4_to_8() (and by png_set_expand() + if there is no transparency in the original or the final + format). "C" means the transformation is obtained by png_set_gray_to_rgb(). "G" means the transformation is obtained by png_set_rgb_to_gray(). "P" means the transformation is obtained by png_set_expand_palette_to_rgb(). "p" means the transformation is obtained by png_set_packing(). "Q" means the transformation is obtained by png_set_quantize(). - "T" means the transformation is obtained by png_set_tRNS_to_alpha(). - "B" means the transformation is obtained by png_set_background(), or - png_strip_alpha(). + "T" means the transformation is obtained by + png_set_tRNS_to_alpha(). + "B" means the transformation is obtained by + png_set_background(), or png_strip_alpha(). When an entry has multiple transforms listed all are required to cause the right overall transformation. When two transforms are separated by a comma @@ -1666,8 +1879,8 @@ with alpha. if (color_type == PNG_COLOR_TYPE_RGB || color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_rgb_to_gray(png_ptr, error_action, double red_weight, - double green_weight); + png_set_rgb_to_gray(png_ptr, error_action, + double red_weight, double green_weight); error_action = 1: silently do the conversion @@ -1689,7 +1902,8 @@ with alpha. In the corresponding fixed point API the red_weight and green_weight values are simply scaled by 100,000: - png_set_rgb_to_gray(png_ptr, error_action, png_fixed_point red_weight, + png_set_rgb_to_gray(png_ptr, error_action, + png_fixed_point red_weight, png_fixed_point green_weight); If you have set error_action = 1 or 2, you can @@ -1733,7 +1947,7 @@ the current display (e.g., the background color from a web page). You need to tell libpng how the color is represented, both the format of the component values in the color (the number of bits) and the gamma encoding of the color. The function takes two arguments, background_gamma_mode and need_expand -to convey this information, however only two combinations are likely to be +to convey this information; however, only two combinations are likely to be useful: png_color_16 my_background; @@ -1780,7 +1994,7 @@ value when you call it in this position: png_set_gamma(png_ptr, screen_gamma, 0.45455); If you need to reduce an RGB file to a paletted file, or if a paletted -file has more entries then will fit on your screen, png_set_quantize() +file has more entries than will fit on your screen, png_set_quantize() will do that. Note that this is a simple match quantization that merely finds the closest color available. This should work fairly well with optimized palettes, but fairly badly with linear color cubes. If you @@ -2027,7 +2241,7 @@ the second parameter NULL. If you don't want libpng to handle the interlacing details, just call png_read_rows() PNG_INTERLACE_ADAM7_PASSES times to read in all the images. -Each of the images is a valid image by itself, however you will almost +Each of the images is a valid image by itself; however, you will almost certainly need to distribute the pixels from each sub-image to the correct place. This is where everything gets very tricky. @@ -2118,10 +2332,15 @@ how pngvalid.c does it. Finishing a sequential read After you are finished reading the image through the -low-level interface, you can finish reading the file. If you are -interested in comments or time, which may be stored either before or -after the image data, you should pass the separate png_info struct if -you want to keep the comments from before and after the image +low-level interface, you can finish reading the file. + +If you want to use a different crc action for handling CRC errors in +chunks after the image data, you can call png_set_crc_action() +again at this point. + +If you are interested in comments or time, which may be stored either +before or after the image data, you should pass the separate png_info +struct if you want to keep the comments from before and after the image separate. png_infop end_info = png_create_info_struct(png_ptr); @@ -2137,6 +2356,9 @@ separate. If you are not interested, you should still call png_read_end() but you can pass NULL, avoiding the need to create an end_info structure. +If you do this, libpng will not process any chunks after IDAT other than +skipping over them and perhaps (depending on whether you have called +png_set_crc_action) checking their CRCs while looking for the IEND chunk. png_read_end(png_ptr, (png_infop)NULL); @@ -2184,7 +2406,7 @@ sPLT, only the n'th item in the structure is freed, where n is "seq". The default behavior is only to free data that was allocated internally by libpng. This can be changed, so that libpng will not free the data, or so that it will free data that was allocated by the user with png_malloc() -or png_zalloc() and passed in via a png_set_*() function, with +or png_calloc() and passed in via a png_set_*() function, with png_data_freer(png_ptr, info_ptr, freer, mask) @@ -2205,7 +2427,7 @@ or png_destroy_*() is supposed to free the data. When the user assumes responsibility for libpng-allocated data, the application must use png_free() to free it, and when the user transfers responsibility to libpng for data that the user has allocated, the user must have used png_malloc() -or png_zalloc() to allocate it. +or png_calloc() to allocate it. If you allocated your row_pointers in a single block, as suggested above in the description of the high level read interface, you must not transfer @@ -2241,7 +2463,7 @@ For a more compact example of reading a PNG image, see the file example.c. Reading PNG files progressively -The progressive reader is slightly different then the non-progressive +The progressive reader is slightly different from the non-progressive reader. Instead of calling png_read_info(), png_read_rows(), and png_read_end(), you make one call to png_process_data(), which calls callbacks when it has the info, a row, or the end of the image. You @@ -2325,7 +2547,7 @@ png_infop info_ptr; 64K. The library seems to run fine with sizes of 4K. Although you can give it much less if necessary (I assume you can give it chunks of - 1 byte, I haven't tried less then 256 bytes + 1 byte, I haven't tried less than 256 bytes yet). When this function returns, you may want to display any rows that were generated in the row callback if you don't already do @@ -2412,7 +2634,7 @@ png_infop info_ptr; png_progressive_combine_row(png_ptr, old_row, new_row); - /* where old_row is what was displayed for + /* where old_row is what was displayed previously for the row. Note that the first pass (pass == 0, really) will completely cover the old row, so the rows do not have to be @@ -2521,6 +2743,20 @@ You can #define PNG_ABORT() to a function that does something more useful than abort(), as long as your function does not return. +Checking for invalid palette index on write was added at libpng +1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues +a benign error. This is enabled by default because this condition is an +error according to the PNG specification, Clause 11.3.2, but the error can +be ignored in each png_ptr with + + png_set_check_for_invalid_index(png_ptr, 0); + +If the error is ignored, or if png_benign_error() treats it as a warning, +any invalid pixels are written as-is by the encoder, resulting in an +invalid PNG datastream as output. In this case the application is +responsible for ensuring that the pixel indexes are in range when it writes +a PLTE chunk with fewer entries than the bit depth would allow. + Now you need to set up the output code. The default for libpng is to use the C function fwrite(). If you use this, you will need to pass a valid FILE * in the function png_init_io(). Be sure that the file is @@ -3023,18 +3259,53 @@ tEXt chunk use RFC 1123 format dates (e.g. "22 May 1997 18:07:10 GMT"), although this isn't a requirement. Unlike the tIME chunk, the "Creation Time" tEXt chunk is not expected to be automatically changed by the software. To facilitate the use of RFC 1123 dates, a function -png_convert_to_rfc1123(png_timep) is provided to convert from PNG -time to an RFC 1123 format string. +png_convert_to_rfc1123_buffer(buffer, png_timep) is provided to +convert from PNG time to an RFC 1123 format string. The caller must provide +a writeable buffer of at least 29 bytes. Writing unknown chunks -You can use the png_set_unknown_chunks function to queue up chunks -for writing. You give it a chunk name, raw data, and a size; that's -all there is to it. The chunks will be written by the next following -png_write_info_before_PLTE, png_write_info, or png_write_end function. -Any chunks previously read into the info structure's unknown-chunk -list will also be written out in a sequence that satisfies the PNG -specification's ordering rules. +You can use the png_set_unknown_chunks function to queue up private chunks +for writing. You give it a chunk name, location, raw data, and a size. You +also must use png_set_keep_unknown_chunks() to ensure that libpng will +handle them. That's all there is to it. The chunks will be written by the +next following png_write_info_before_PLTE, png_write_info, or png_write_end +function, depending upon the specified location. Any chunks previously +read into the info structure's unknown-chunk list will also be written out +in a sequence that satisfies the PNG specification's ordering rules. + +Here is an example of writing two private chunks, prVt and miNE: + + #ifdef PNG_WRITE_UNKNOWN_CHUNKS_SUPPORTED + /* Set unknown chunk data */ + png_unknown_chunk unk_chunk[2]; + strcpy((char *) unk_chunk[0].name, "prVt"; + unk_chunk[0].data = (unsigned char *) "PRIVATE DATA"; + unk_chunk[0].size = strlen(unk_chunk[0].data)+1; + unk_chunk[0].location = PNG_HAVE_IHDR; + strcpy((char *) unk_chunk[1].name, "miNE"; + unk_chunk[1].data = (unsigned char *) "MY CHUNK DATA"; + unk_chunk[1].size = strlen(unk_chunk[0].data)+1; + unk_chunk[1].location = PNG_AFTER_IDAT; + png_set_unknown_chunks(write_ptr, write_info_ptr, + unk_chunk, 2); + /* Needed because miNE is not safe-to-copy */ + png_set_keep_unknown_chunks(png, PNG_HANDLE_CHUNK_ALWAYS, + (png_bytep) "miNE", 1); + # if PNG_LIBPNG_VER < 10600 + /* Deal with unknown chunk location bug in 1.5.x and earlier */ + png_set_unknown_chunk_location(png, info, 0, PNG_HAVE_IHDR); + png_set_unknown_chunk_location(png, info, 1, PNG_AFTER_IDAT); + # endif + # if PNG_LIBPNG_VER < 10500 + /* PNG_AFTER_IDAT writes two copies of the chunk prior to libpng-1.5.0, + * one before IDAT and another after IDAT, so don't use it; only use + * PNG_HAVE_IHDR location. This call resets the location previously + * set by assignment and png_set_unknown_chunk_location() for chunk 1. + */ + png_set_unknown_chunk_location(png, info, 1, PNG_HAVE_IHDR); + # endif + #endif The high-level write interface @@ -3386,7 +3657,7 @@ png_destroy_write_struct(). The default behavior is only to free data that was allocated internally by libpng. This can be changed, so that libpng will not free the data, or so that it will free data that was allocated by the user with png_malloc() -or png_zalloc() and passed in via a png_set_*() function, with +or png_calloc() and passed in via a png_set_*() function, with png_data_freer(png_ptr, info_ptr, freer, mask) @@ -3422,7 +3693,7 @@ When the user assumes responsibility for libpng-allocated data, the application must use png_free() to free it, and when the user transfers responsibility to libpng for data that the user has allocated, the user must have used png_malloc() -or png_zalloc() to allocate it. +or png_calloc() to allocate it. If you allocated text_ptr.text, text_ptr.lang, and text_ptr.translated_keyword separately, do not transfer responsibility for freeing text_ptr to libpng, @@ -3432,7 +3703,374 @@ if you transfer responsibility for free'ing text_ptr from libpng to your application, your application must not separately free those members. For a more compact example of writing a PNG image, see the file example.c. -V. Modifying/Customizing libpng: +V. Simplified API + +The simplified API, which became available in libpng-1.6.0, hides the details +of both libpng and the PNG file format itself. +It allows PNG files to be read into a very limited number of +in-memory bitmap formats or to be written from the same formats. If these +formats do not accommodate your needs then you can, and should, use the more +sophisticated APIs above - these support a wide variety of in-memory formats +and a wide variety of sophisticated transformations to those formats as well +as a wide variety of APIs to manipulate ancilliary information. + +To read a PNG file using the simplified API: + + 1) Declare a 'png_image' structure (see below) on the + stack and memset() it to all zero. + + 2) Call the appropriate png_image_begin_read... function. + + 3) Set the png_image 'format' member to the required + format and allocate a buffer for the image. + + 4) Call png_image_finish_read to read the image into + your buffer. + +There are no restrictions on the format of the PNG input itself; all valid +color types, bit depths, and interlace methods are acceptable, and the +input image is transformed as necessary to the requested in-memory format +during the png_image_finish_read() step. + +To write a PNG file using the simplified API: + + 1) Declare a 'png_image' structure on the stack and memset() + it to all zero. + + 2) Initialize the members of the structure that describe the + image, setting the 'format' member to the format of the + image in memory. + + 3) Call the appropriate png_image_write... function with a + pointer to the image to write the PNG data. + +png_image is a structure that describes the in-memory format of an image +when it is being read or define the in-memory format of an image that you +need to write. The "png_image" structure contains the following members: + + png_uint_32 version Set to PNG_IMAGE_VERSION + png_uint_32 width Image width in pixels (columns) + png_uint_32 height Image height in pixels (rows) + png_uint_32 format Image format as defined below + png_uint_32 flags A bit mask containing informational flags + png_controlp opaque Initialize to NULL, free with png_image_free + png_uint_32 colormap_entries; Number of entries in the color-map + png_uint_32 warning_or_error; + char message[64]; + +In the event of an error or warning the following field warning_or_error +field will be set to a non-zero value and the 'message' field will contain +a '\0' terminated string with the libpng error or warning message. If both +warnings and an error were encountered, only the error is recorded. If there +are multiple warnings, only the first one is recorded. + +The upper 30 bits of this value are reserved; the low two bits contain +a two bit code such that a value more than 1 indicates a failure in the API +just called: + + 0 - no warning or error + 1 - warning + 2 - error + 3 - error preceded by warning + +The pixels (samples) of the image have one to four channels whose components +have original values in the range 0 to 1.0: + + 1: A single gray or luminance channel (G). + 2: A gray/luminance channel and an alpha channel (GA). + 3: Three red, green, blue color channels (RGB). + 4: Three color channels and an alpha channel (RGBA). + +The channels are encoded in one of two ways: + + a) As a small integer, value 0..255, contained in a single byte. For the +alpha channel the original value is simply value/255. For the color or +luminance channels the value is encoded according to the sRGB specification +and matches the 8-bit format expected by typical display devices. + +The color/gray channels are not scaled (pre-multiplied) by the alpha +channel and are suitable for passing to color management software. + + b) As a value in the range 0..65535, contained in a 2-byte integer, in +the native byte order of the platform on which the application is running. +All channels can be converted to the original value by dividing by 65535; all +channels are linear. Color channels use the RGB encoding (RGB end-points) of +the sRGB specification. This encoding is identified by the +PNG_FORMAT_FLAG_LINEAR flag below. + +When an alpha channel is present it is expected to denote pixel coverage +of the color or luminance channels and is returned as an associated alpha +channel: the color/gray channels are scaled (pre-multiplied) by the alpha +value. + +When a color-mapped image is used as a result of calling +png_image_read_colormap or png_image_write_colormap the channels are encoded +in the color-map and the descriptions above apply to the color-map entries. +The image data is encoded as small integers, value 0..255, that index the +entries in the color-map. One integer (one byte) is stored for each pixel. + +PNG_FORMAT_* + +The #defines to be used in png_image::format. Each #define identifies a +particular layout of channel data and, if present, alpha values. There are +separate defines for each of the two channel encodings. + +A format is built up using single bit flag values. Not all combinations are +valid: use the bit flag values below for testing a format returned by the +read APIs, but set formats from the derived values. + +When reading or writing color-mapped images the format should be set to the +format of the entries in the color-map then png_image_{read,write}_colormap +called to read or write the color-map and set the format correctly for the +image data. Do not set the PNG_FORMAT_FLAG_COLORMAP bit directly! + +NOTE: libpng can be built with particular features disabled, if you see +compiler errors because the definition of one of the following flags has been +compiled out it is because libpng does not have the required support. It is +possible, however, for the libpng configuration to enable the format on just +read or just write; in that case you may see an error at run time. You can +guard against this by checking for the definition of: + + PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED + + PNG_FORMAT_FLAG_ALPHA 0x01 format with an alpha channel + PNG_FORMAT_FLAG_COLOR 0x02 color format: otherwise grayscale + PNG_FORMAT_FLAG_LINEAR 0x04 png_uint_16 channels else png_byte + PNG_FORMAT_FLAG_COLORMAP 0x08 libpng use only + PNG_FORMAT_FLAG_BGR 0x10 BGR colors, else order is RGB + PNG_FORMAT_FLAG_AFIRST 0x20 alpha channel comes first + +Supported formats are as follows. Future versions of libpng may support more +formats; for compatibility with older versions simply check if the format +macro is defined using #ifdef. These defines describe the in-memory layout +of the components of the pixels of the image. + +First the single byte formats: + + PNG_FORMAT_GRAY 0 + PNG_FORMAT_GA PNG_FORMAT_FLAG_ALPHA + PNG_FORMAT_AG (PNG_FORMAT_GA|PNG_FORMAT_FLAG_AFIRST) + PNG_FORMAT_RGB PNG_FORMAT_FLAG_COLOR + PNG_FORMAT_BGR (PNG_FORMAT_FLAG_COLOR|PNG_FORMAT_FLAG_BGR) + PNG_FORMAT_RGBA (PNG_FORMAT_RGB|PNG_FORMAT_FLAG_ALPHA) + PNG_FORMAT_ARGB (PNG_FORMAT_RGBA|PNG_FORMAT_FLAG_AFIRST) + PNG_FORMAT_BGRA (PNG_FORMAT_BGR|PNG_FORMAT_FLAG_ALPHA) + PNG_FORMAT_ABGR (PNG_FORMAT_BGRA|PNG_FORMAT_FLAG_AFIRST) + +Then the linear 2-byte formats. When naming these "Y" is used to +indicate a luminance (gray) channel. The component order within the pixel +is always the same - there is no provision for swapping the order of the +components in the linear format. The components are 16-bit integers in +the native byte order for your platform, and there is no provision for +swapping the bytes to a different endian condition. + + PNG_FORMAT_LINEAR_Y PNG_FORMAT_FLAG_LINEAR + PNG_FORMAT_LINEAR_Y_ALPHA + (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_ALPHA) + PNG_FORMAT_LINEAR_RGB + (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR) + PNG_FORMAT_LINEAR_RGB_ALPHA + (PNG_FORMAT_FLAG_LINEAR|PNG_FORMAT_FLAG_COLOR| + PNG_FORMAT_FLAG_ALPHA) + +Color-mapped formats are obtained by calling png_image_{read,write}_colormap, +as appropriate after setting png_image::format to the format of the color-map +to be read or written. Applications may check the value of +PNG_FORMAT_FLAG_COLORMAP to see if they have called the colormap API. The +format of the color-map may be extracted using the following macro. + + PNG_FORMAT_OF_COLORMAP(fmt) ((fmt) & ~PNG_FORMAT_FLAG_COLORMAP) + +PNG_IMAGE macros + +These are convenience macros to derive information from a png_image +structure. The PNG_IMAGE_SAMPLE_ macros return values appropriate to the +actual image sample values - either the entries in the color-map or the +pixels in the image. The PNG_IMAGE_PIXEL_ macros return corresponding values +for the pixels and will always return 1 after a call to +png_image_{read,write}_colormap. The remaining macros return information +about the rows in the image and the complete image. + +NOTE: All the macros that take a png_image::format parameter are compile time +constants if the format parameter is, itself, a constant. Therefore these +macros can be used in array declarations and case labels where required. +Similarly the macros are also pre-processor constants (sizeof is not used) so +they can be used in #if tests. + +First the information about the samples. + + PNG_IMAGE_SAMPLE_CHANNELS(fmt) + Returns the total number of channels in a given format: 1..4 + + PNG_IMAGE_SAMPLE_COMPONENT_SIZE(fmt) + Returns the size in bytes of a single component of a pixel or color-map + entry (as appropriate) in the image. + + PNG_IMAGE_SAMPLE_SIZE(fmt) + This is the size of the sample data for one sample. If the image is + color-mapped it is the size of one color-map entry (and image pixels are + one byte in size), otherwise it is the size of one image pixel. + + PNG_IMAGE_COLORMAP_SIZE(fmt) + The size of the color-map required by the format; this is the size of the + color-map buffer passed to the png_image_{read,write}_colormap APIs, it is + a fixed number determined by the format so can easily be allocated on the + stack if necessary. + +#define PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(fmt)\ + (PNG_IMAGE_SAMPLE_CHANNELS(fmt) * 256) + /* The maximum size of the color-map required by the format expressed in a + * count of components. This can be used to compile-time allocate a + * color-map: + * + * png_uint_16 colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(linear_fmt)]; + * + * png_byte colormap[PNG_IMAGE_MAXIMUM_COLORMAP_COMPONENTS(sRGB_fmt)]; + * + * Alternatively, use the PNG_IMAGE_COLORMAP_SIZE macro below to use the + * information from one of the png_image_begin_read_ APIs and dynamically + * allocate the required memory. + */ + + +Corresponding information about the pixels + + PNG_IMAGE_PIXEL_(test,fmt) + + PNG_IMAGE_PIXEL_CHANNELS(fmt) + The number of separate channels (components) in a pixel; 1 for a + color-mapped image. + + PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt)\ + The size, in bytes, of each component in a pixel; 1 for a color-mapped + image. + + PNG_IMAGE_PIXEL_SIZE(fmt) + The size, in bytes, of a complete pixel; 1 for a color-mapped image. + +Information about the whole row, or whole image + + PNG_IMAGE_ROW_STRIDE(image) + Returns the total number of components in a single row of the image; this + is the minimum 'row stride', the minimum count of components between each + row. For a color-mapped image this is the minimum number of bytes in a + row. + + If you need the stride measured in bytes, row_stride_bytes is + PNG_IMAGE_ROW_STRIDE(image) * PNG_IMAGE_PIXEL_COMPONENT_SIZE(fmt) + plus any padding bytes that your application might need, for example + to start the next row on a 4-byte boundary. + + PNG_IMAGE_BUFFER_SIZE(image, row_stride) + Returns the size, in bytes, of an image buffer given a png_image and a row + stride - the number of components to leave space for in each row. This + macro takes care of multiplying row_stride by PNG_IMAGE_PIXEL_COMONENT_SIZE + when the image has 2-byte components. + + PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB == 0x01 + This indicates the the RGB values of the in-memory bitmap do not + correspond to the red, green and blue end-points defined by sRGB. + + PNG_IMAGE_FLAG_COLORMAP == 0x02 + The PNG is color-mapped. If this flag is set png_image_read_colormap + can be used without further loss of image information. If it is not set + png_image_read_colormap will cause significant loss if the image has any + +READ APIs + + The png_image passed to the read APIs must have been initialized by setting + the png_controlp field 'opaque' to NULL (or, better, memset the whole thing.) + + int png_image_begin_read_from_file( png_imagep image, + const char *file_name) + + The named file is opened for read and the image header + is filled in from the PNG header in the file. + + int png_image_begin_read_from_stdio (png_imagep image, + FILE* file) + + The PNG header is read from the stdio FILE object. + + int png_image_begin_read_from_memory(png_imagep image, + png_const_voidp memory, png_size_t size) + + The PNG header is read from the given memory buffer. + + int png_image_finish_read(png_imagep image, + png_colorp background, void *buffer, + png_int_32 row_stride, void *colormap)); + + Finish reading the image into the supplied buffer and + clean up the png_image structure. + + row_stride is the step, in png_byte or png_uint_16 units + as appropriate, between adjacent rows. A positive stride + indicates that the top-most row is first in the buffer - + the normal top-down arrangement. A negative stride + indicates that the bottom-most row is first in the buffer. + + background need only be supplied if an alpha channel must + be removed from a png_byte format and the removal is to be + done by compositing on a solid color; otherwise it may be + NULL and any composition will be done directly onto the + buffer. The value is an sRGB color to use for the + background, for grayscale output the green channel is used. + + For linear output removing the alpha channel is always done + by compositing on black. + + void png_image_free(png_imagep image) + + Free any data allocated by libpng in image->opaque, + setting the pointer to NULL. May be called at any time + after the structure is initialized. + +When the simplified API needs to convert between sRGB and linear colorspaces, +the actual sRGB transfer curve defined in the sRGB specification (see the +article at http://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 +approximation used elsewhere in libpng. + +WRITE APIS + +For write you must initialize a png_image structure to describe the image to +be written: + + version: must be set to PNG_IMAGE_VERSION + opaque: must be initialized to NULL + width: image width in pixels + height: image height in rows + format: the format of the data you wish to write + flags: set to 0 unless one of the defined flags applies; set + PNG_IMAGE_FLAG_COLORSPACE_NOT_sRGB for color format images + where the RGB values do not correspond to the colors in sRGB. + colormap_entries: set to the number of entries in the color-map (0 to 256) + + int png_image_write_to_file, (png_imagep image, + const char *file, int convert_to_8bit, const void *buffer, + png_int_32 row_stride, const void *colormap)); + + Write the image to the named file. + + int png_image_write_to_stdio(png_imagep image, FILE *file, + int convert_to_8_bit, const void *buffer, + png_int_32 row_stride, const void *colormap) + + Write the image to the given (FILE*). + +With all write APIs if image is in one of the linear formats with +(png_uint_16) data then setting convert_to_8_bit will cause the output to be +a (png_byte) PNG gamma encoded according to the sRGB specification, otherwise +a 16-bit linear encoded PNG file is written. + +With all APIs row_stride is handled as in the read APIs - it is the spacing +from one row to the next in component sized units (float) and if negative +indicates a bottom-up row layout in the buffer. + +Note that the write API does not support interlacing, sub-8-bit pixels, +and indexed (paletted) images. + +VI. Modifying/Customizing libpng There are two issues here. The first is changing how libpng does standard things like memory allocation, input/output, and error handling. @@ -3450,19 +4088,17 @@ in pngmem.c, pngrio.c, pngwio.c, and pngerror.c, respectively. To change these functions, call the appropriate png_set_*_fn() function. Memory allocation is done through the functions png_malloc(), png_calloc(), -and png_free(). These currently just call the standard C functions. -png_calloc() calls png_malloc() and then clears the newly -allocated memory to zero. There is limited support for certain systems -with segmented memory architectures and the types of pointers declared by -png.h match this; you will have to use appropriate pointers in your -application. Since it is -unlikely that the method of handling memory allocation on a platform -will change between applications, these functions must be modified in -the library at compile time. If you prefer to use a different method -of allocating and freeing data, you can use png_create_read_struct_2() or -png_create_write_struct_2() to register your own functions as described -above. These functions also provide a void pointer that can be retrieved -via +and png_free(). The png_malloc() and png_free() functions currently just +call the standard C functions and png_calloc() calls png_malloc() and then +clears the newly allocated memory to zero; note that png_calloc(png_ptr, size) +is not the same as the calloc(number, size) function provided by stdlib.h. +There is limited support for certain systems with segmented memory +architectures and the types of pointers declared by png.h match this; you +will have to use appropriate pointers in your application. If you prefer +to use a different method of allocating and freeing data, you can use +png_create_read_struct_2() or png_create_write_struct_2() to register your +own functions as described above. These functions also provide a void +pointer that can be retrieved via mem_ptr=png_get_mem_ptr(png_ptr); @@ -3565,6 +4201,18 @@ compiler documentation for more details. For an alternative approach, you may wish to use the "cexcept" facility (see http://cexcept.sourceforge.net), which is illustrated in pngvalid.c and in contrib/visupng. +Beginning in libpng-1.4.0, the png_set_benign_errors() API became available. +You can use this to handle certain errors (normally handled as errors) +as warnings. + + png_set_benign_errors (png_ptr, int allowed); + + allowed: 0: treat png_benign_error() as an error. + 1: treat png_benign_error() as a warning. + +As of libpng-1.6.0, the default condition is to treat benign errors as +warnings while reading and as errors while writing. + Custom chunks If you need to read or write custom chunks, you may need to get deeper @@ -3593,29 +4241,6 @@ the simpler ones to get an idea of how they work. Try to find a similar transformation to the one you want to add and copy off of it. More details can be found in the comments inside the code itself. -Configuring for 16-bit platforms - -You will want to look into zconf.h to tell zlib (and thus libpng) that -it cannot allocate more then 64K at a time. Even if you can, the memory -won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K. - -Configuring for DOS - -For DOS users who only have access to the lower 640K, you will -have to limit zlib's memory usage via a png_set_compression_mem_level() -call. See zlib.h or zconf.h in the zlib library for more information. - -Configuring for Medium Model - -Libpng's support for medium model has been tested on most of the popular -compilers. Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets -defined, and FAR gets defined to far in pngconf.h, and you should be -all set. Everything in the library (except for zlib's structure) is -expecting far data. You must use the typedefs with the p or pp on -the end for pointers (or at least look at them and be careful). Make -note that the rows of data are defined as png_bytepp, which is -an "unsigned char far * far *". - Configuring for gui/windowing platforms: You will need to write new error and warning functions that use the GUI @@ -3625,18 +4250,6 @@ in order to have them available during the structure initialization. They can be changed later via png_set_error_fn(). On some compilers, you may also have to change the memory allocators (png_malloc, etc.). -Configuring for compiler xxx: - -All includes for libpng are in pngconf.h. If you need to add, change -or delete an include, this is the place to do it. -The includes that are not needed outside libpng are placed in pngpriv.h, -which is only used by the routines inside libpng itself. -The files in libpng proper only include pngpriv.h and png.h, which -in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h. -As of libpng-1.5.0, pngpriv.h also includes three other private header -files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material -that previously appeared in the public headers. - Configuring zlib: There are special functions to configure the compression. Perhaps the @@ -3678,6 +4291,8 @@ zlib.h for more information on what these mean. png_set_compression_method(png_ptr, method); +This controls the size of the IDAT chunks (default 8192): + png_set_compression_buffer_size(png_ptr, size); As of libpng version 1.5.4, additional APIs became @@ -3685,7 +4300,7 @@ available to set these separately for non-IDAT compressed chunks such as zTXt, iTXt, and iCCP: #include zlib.h - #if PNG_LIBPNG_VER <= 10504 + #if PNG_LIBPNG_VER >= 10504 png_set_text_compression_level(png_ptr, level); png_set_text_compression_mem_level(png_ptr, level); @@ -3776,46 +4391,6 @@ Note that the numbers above were invented purely for this example and are given only to help explain the function usage. Little testing has been done to find optimum values for either the costs or the weights. -Removing unwanted object code - -There are a bunch of #define's in pngconf.h that control what parts of -libpng are compiled. All the defines end in _SUPPORTED. If you are -never going to use a capability, you can change the #define to #undef -before recompiling libpng and save yourself code and data space, or -you can turn off individual capabilities with defines that begin with -PNG_NO_. - -In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead. - -You can also turn all of the transforms and ancillary chunk capabilities -off en masse with compiler directives that define -PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS, -or all four, -along with directives to turn on any of the capabilities that you do -want. The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the extra -transformations but still leave the library fully capable of reading -and writing PNG files with all known public chunks. Use of the -PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library -that is incapable of reading or writing ancillary chunks. If you are -not using the progressive reading capability, you can turn that off -with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING -capability, which you'll still have). - -All the reading and writing specific code are in separate files, so the -linker should only grab the files it needs. However, if you want to -make sure, or if you are building a stand alone library, all the -reading files start with "pngr" and all the writing files start with "pngw". -The files that don't match either (like png.c, pngtrans.c, etc.) -are used for both reading and writing, and always need to be included. -The progressive reader is in pngpread.c - -If you are creating or distributing a dynamically linked library (a .so -or DLL file), you should not remove or disable any parts of the library, -as this will cause applications linked with different versions of the -library to fail if they call functions not available in your library. -The size of the library itself should not be an issue, because only -those sections that are actually used will be loaded into memory. - Requesting debug printout The macro definition PNG_DEBUG can be used to request debugging @@ -3835,7 +4410,7 @@ the message, "message" is the formatted string to be printed, and p1 and p2 are parameters that are to be embedded in the string according to printf-style formatting directives. For example, - png_debug1(2, "foo=%d\n", foo); + png_debug1(2, "foo=%d", foo); is expanded to @@ -3853,7 +4428,7 @@ When PNG_DEBUG = 1, the macros are defined, but only png_debug statements having level = 0 will be printed. There aren't any such statements in this version of libpng, but if you insert some they will be printed. -VI. MNG support +VII. MNG support The MNG specification (available at http://www.libpng.org/pub/mng) allows certain extensions to PNG for PNG images that are embedded in MNG datastreams. @@ -3880,7 +4455,7 @@ or any other MNG chunks; your application must provide its own support for them. You may wish to consider using libmng (available at http://www.libmng.com) instead. -VII. Changes to Libpng from version 0.88 +VIII. Changes to Libpng from version 0.88 It should be noted that versions of libpng later than 0.96 are not distributed by the original libpng author, Guy Schalnat, nor by @@ -3915,6 +4490,9 @@ png_set_error_fn(), which is essentially the same function, but with a new name to force compilation errors with applications that try to use the old method. +Support for the sCAL, iCCP, iTXt, and sPLT chunks was added at libpng-1.0.6; +however, iTXt support was not enabled by default. + Starting with version 1.0.7, you can find out which version of the library you are using at run-time: @@ -3932,7 +4510,7 @@ application: png_uint_32 application_vn = PNG_LIBPNG_VER; -VIII. Changes to Libpng from version 1.0.x to 1.2.x +IX. Changes to Libpng from version 1.0.x to 1.2.x Support for user memory management was enabled by default. To accomplish this, the functions png_create_read_struct_2(), @@ -4029,7 +4607,7 @@ which also expands tRNS to alpha was replaced with png_set_expand_gray_1_2_4_to_8() which does not. It has been deprecated since libpng-1.0.18 and 1.2.9. -IX. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x +X. Changes to Libpng from version 1.0.x/1.2.x to 1.4.x Private libpng prototypes and macro definitions were moved from png.h and pngconf.h into a new pngpriv.h header file. @@ -4122,14 +4700,16 @@ png_set_strip_error_numbers() was removed from the library by default. The png_zalloc() and png_zfree() functions are no longer exported. The png_zalloc() function no longer zeroes out the memory that it -allocates. +allocates. Applications that called png_zalloc(png_ptr, number, size) +can call png_calloc(png_ptr, number*size) instead, and can call +png_free() instead of png_zfree(). Support for dithering was disabled by default in libpng-1.4.0, because it has not been well tested and doesn't actually "dither". The code was not removed, however, and could be enabled by building libpng with PNG_READ_DITHER_SUPPORTED defined. In libpng-1.4.2, this support -was reenabled, but the function was renamed png_set_quantize() to +was re-enabled, but the function was renamed png_set_quantize() to reflect more accurately what it actually does. At the same time, the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros were also renamed to PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS, and PNG_READ_DITHER_SUPPORTED @@ -4137,37 +4717,61 @@ was renamed to PNG_READ_QUANTIZE_SUPPORTED. We removed the trailing '.' from the warning and error messages. -X. Changes to Libpng from version 1.4.x to 1.5.x +XI. Changes to Libpng from version 1.4.x to 1.5.x From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the function) incorrectly returned a value of type png_uint_32. +The incorrect macro was removed from libpng-1.4.5. -Checking for invalid palette index on read or write was added at libpng -1.5.10. When an invalid index is found, libpng issues a benign error. -This is enabled by default but can be disabled in each png_ptr with +Checking for invalid palette index on write was added at libpng +1.5.10. If a pixel contains an invalid (out-of-range) index libpng issues +a benign error. This is enabled by default because this condition is an +error according to the PNG specification, Clause 11.3.2, but the error can +be ignored in each png_ptr with png_set_check_for_invalid_index(png_ptr, allowed); allowed - one of - 0: disable - 1: enable + 0: disable benign error (accept the + invalid data without warning). + 1: enable benign error (treat the + invalid data as an error or a + warning). + +If the error is ignored, or if png_benign_error() treats it as a warning, +any invalid pixels are decoded as opaque black by the decoder and written +as-is by the encoder. + +Retrieving the maximum palette index found was added at libpng-1.5.15. +This statement must appear after png_read_png() or png_read_image() while +reading, and after png_write_png() or png_write_image() while writing. + + int max_palette = png_get_palette_max(png_ptr, info_ptr); -A. Changes that affect users of libpng +This will return the maximum palette index found in the image, or "-1" if +the palette was not checked, or "0" if no palette was found. Note that this +does not account for any palette index used by ancillary chunks such as the +bKGD chunk; you must check those separately to determine the maximum +palette index actually used. There are no substantial API changes between the non-deprecated parts of -the 1.4.5 API and the 1.5.0 API, however the ability to directly access -the main libpng control structures, png_struct and png_info, deprecated -in earlier versions of libpng, has been completely removed from +the 1.4.5 API and the 1.5.0 API; however, the ability to directly access +members of the main libpng control structures, png_struct and png_info, +deprecated in earlier versions of libpng, has been completely removed from libpng 1.5. -We no longer include zlib.h in png.h. Applications that need access -to information in zlib.h will need to add the '#include "zlib.h"' -directive. It does not matter whether it is placed prior to or after +We no longer include zlib.h in png.h. The include statement has been moved +to pngstruct.h, where it is not accessible by applications. Applications that +need access to information in zlib.h will need to add the '#include "zlib.h"' +directive. It does not matter whether this is placed prior to or after the '"#include png.h"' directive. -We moved the png_strcpy(), png_strncpy(), png_strlen(), png_memcpy(), -png_memcmp(), png_sprintf, and png_memcpy() macros into a private -header file (pngpriv.h) that is not accessible to applications. +The png_sprintf(), png_strcpy(), and png_strncpy() macros are no longer used +and were removed. + +We moved the png_strlen(), png_memcpy(), png_memset(), and png_memcmp() +macros into a private header file (pngpriv.h) that is not accessible to +applications. In png_get_iCCP, the type of "profile" was changed from png_charpp to png_bytepp, and in png_set_iCCP, from png_charp to png_const_bytep. @@ -4220,7 +4824,10 @@ and the accuracy of PNG fixed point values is insufficient for representation of these values. Consequently a "string" API (png_get_sCAL_s and png_set_sCAL_s) is the only reliable way of reading arbitrary sCAL chunks in the absence of either the floating point API or -internal floating point calculations. +internal floating point calculations. Starting with libpng-1.5.0, both +of these functions are present when PNG_sCAL_SUPPORTED is defined. Prior +to libpng-1.5.0, their presence also depended upon PNG_FIXED_POINT_SUPPORTED +being defined and PNG_FLOATING_POINT_SUPPORTED not being defined. Applications no longer need to include the optional distribution header file pngusr.h or define the corresponding macros during application @@ -4240,15 +4847,10 @@ reset by pngusr.h or by explicit settings on the compiler command line. These settings may produce compiler warnings or errors in 1.5.0 because of macro redefinition. -From libpng-1.4.0 until 1.4.4, the png_get_uint_16 macro (but not the -function) incorrectly returned a value of type png_uint_32. libpng 1.5.0 -is consistent with the implementation in 1.4.5 and 1.2.x (where the macro -did not exist.) - Applications can now choose whether to use these macros or to call the corresponding function by defining PNG_USE_READ_MACROS or PNG_NO_USE_READ_MACROS before including png.h. Notice that this is -only supported from 1.5.0 -defining PNG_NO_USE_READ_MACROS prior to 1.5.0 +only supported from 1.5.0; defining PNG_NO_USE_READ_MACROS prior to 1.5.0 will lead to a link failure. Prior to libpng-1.5.4, the zlib compressor used the same set of parameters @@ -4262,7 +4864,10 @@ option was off by default, and slightly inaccurate scaling occurred. This option can no longer be turned off, and the choice of accurate or inaccurate 16-to-8 scaling is by using the new png_set_scale_16_to_8() API for accurate scaling or the old png_set_strip_16_to_8() API for simple -chopping. +chopping. In libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED +macro became PNG_READ_SCALE_16_TO_8_SUPPORTED, and the PNG_READ_16_TO_8 +macro became PNG_READ_STRIP_16_TO_8_SUPPORTED, to enable the two +png_set_*_16_to_8() functions separately. Prior to libpng-1.5.4, the png_set_user_limits() function could only be used to reduce the width and height limits from the value of @@ -4284,25 +4889,8 @@ limits are now png_user_chunk_cache_max 0 (unlimited) 128 png_user_chunk_malloc_max 0 (unlimited) 8,000,000 -B. Changes to the build and configuration of libpng - -Details of internal changes to the library code can be found in the CHANGES -file and in the GIT repository logs. These will be of no concern to the vast -majority of library users or builders, however the few who configure libpng -to a non-default feature set may need to change how this is done. - -There should be no need for library builders to alter build scripts if -these use the distributed build support - configure or the makefiles - -however users of the makefiles may care to update their build scripts -to build pnglibconf.h where the corresponding makefile does not do so. - -Building libpng with a non-default configuration has changed completely. -The old method using pngusr.h should still work correctly even though the -way pngusr.h is used in the build has been changed; however, library -builders will probably want to examine the changes to take advantage of -new capabilities and to simplify their build system. - -B.1 Specific changes to library configuration capabilities +The png_set_option() function (and the "options" member of the png struct) was +added to libpng-1.5.15. The library now supports a complete fixed point implementation and can thus be used on systems that have no floating point support or very @@ -4314,27 +4902,7 @@ independent of the choice of fixed versus floating point APIs and all the missing fixed point APIs have been implemented. The exact mechanism used to control attributes of API functions has -changed. A single set of operating system independent macro definitions -is used and operating system specific directives are defined in -pnglibconf.h - -As part of this the mechanism used to choose procedure call standards on -those systems that allow a choice has been changed. At present this only -affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems -running on Intel processors. As before, PNGAPI is defined where required -to control the exported API functions; however, two new macros, PNGCBAPI -and PNGCAPI, are used instead for callback functions (PNGCBAPI) and -(PNGCAPI) for functions that must match a C library prototype (currently -only png_longjmp_ptr, which must match the C longjmp function.) The new -approach is documented in pngconf.h - -Despite these changes, libpng 1.5.0 only supports the native C function -calling standard on those platforms tested so far (__cdecl on Microsoft -Windows). This is because the support requirements for alternative -calling conventions seem to no longer exist. Developers who find it -necessary to set PNG_API_RULE to 1 should advise the mailing list -(png-mng-implement) of this and library builders who use Openwatcom and -therefore set PNG_API_RULE to 2 should also contact the mailing list. +changed, as described in the INSTALL file. A new test program, pngvalid, is provided in addition to pngtest. pngvalid validates the arithmetic accuracy of the gamma correction @@ -4399,7 +4967,7 @@ merely stops the function from being exported. PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating point implementation or the fixed point one. Typically the fixed point implementation is larger and slower than the floating point implementation -on a system that supports floating point, however it may be faster on a +on a system that supports floating point; however, it may be faster on a system which lacks floating point hardware and therefore uses a software emulation. @@ -4410,47 +4978,138 @@ even though the default is to use the macros - this allows applications to choose at app buildtime whether or not to use macros (previously impossible because the functions weren't in the default build.) -B.2 Changes to the configuration mechanism - -Prior to libpng-1.5.0 library builders who needed to configure libpng -had either to modify the exported pngconf.h header file to add system -specific configuration or had to write feature selection macros into -pngusr.h and cause this to be included into pngconf.h by defining -PNG_USER_CONFIG. The latter mechanism had the disadvantage that an -application built without PNG_USER_CONFIG defined would see the -unmodified, default, libpng API and thus would probably fail to link. - -These mechanisms still work in the configure build and in any makefile -build that builds pnglibconf.h, although the feature selection macros -have changed somewhat as described above. In 1.5.0, however, pngusr.h is -processed only once, when the exported header file pnglibconf.h is built. -pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the -build of pnglibconf.h and it is never included in an application build. - -The rarely used alternative of adding a list of feature macros to the -CFLAGS setting in the build also still works, however the macros will be -copied to pnglibconf.h and this may produce macro redefinition warnings -when the individual C files are compiled. - -All configuration now only works if pnglibconf.h is built from -scripts/pnglibconf.dfa. This requires the program awk. Brian Kernighan -(the original author of awk) maintains C source code of that awk and this -and all known later implementations (often called by subtly different -names - nawk and gawk for example) are adequate to build pnglibconf.h. -The Sun Microsystems (now Oracle) program 'awk' is an earlier version -and does not work; this may also apply to other systems that have a -functioning awk called 'nawk'. - -Configuration options are now documented in scripts/pnglibconf.dfa. This -file also includes dependency information that ensures a configuration is -consistent; that is, if a feature is switched off dependent features are -also removed. As a recommended alternative to using feature macros in -pngusr.h a system builder may also define equivalent options in pngusr.dfa -(or, indeed, any file) and add that to the configuration by setting -DFA_XTRA to the file name. The makefiles in contrib/pngminim illustrate -how to do this, and a case where pngusr.h is still required. - -XI. Detecting libpng +XII. Changes to Libpng from version 1.5.x to 1.6.x + +A "simplified API" has been added (see documentation in png.h and a simple +example in contrib/examples/pngtopng.c). The new publicly visible API +includes the following: + + macros: + PNG_FORMAT_* + PNG_IMAGE_* + structures: + png_control + png_image + read functions + png_image_begin_read_from_file() + png_image_begin_read_from_stdio() + png_image_begin_read_from_memory() + png_image_finish_read() + png_image_free() + write functions + png_image_write_to_file() + png_image_write_to_stdio() + +Starting with libpng-1.6.0, you can configure libpng to prefix all exported +symbols, using the PNG_PREFIX macro. + +We no longer include string.h in png.h. The include statement has been moved +to pngpriv.h, where it is not accessible by applications. Applications that +need access to information in string.h must add an '#include <string.h>' +directive. It does not matter whether this is placed prior to or after +the '#include "png.h"' directive. + +The following API are now DEPRECATED: + png_info_init_3() + png_convert_to_rfc1123() which has been replaced + with png_convert_to_rfc1123_buffer() + png_malloc_default() + png_free_default() + png_reset_zstream() + +The following have been removed: + png_get_io_chunk_name(), which has been replaced + with png_get_io_chunk_type(). The new + function returns a 32-bit integer instead of + a string. + The png_sizeof(), png_strlen(), png_memcpy(), png_memcmp(), and + png_memset() macros are no longer used in the libpng sources and + have been removed. These had already been made invisible to applications + (i.e., defined in the private pngpriv.h header file) since libpng-1.5.0. + +The signatures of many exported functions were changed, such that + png_structp became png_structrp or png_const_structrp + png_infop became png_inforp or png_const_inforp +where "rp" indicates a "restricted pointer". + +The support for FAR/far types has been eliminated and the definition of +png_alloc_size_t is now controlled by a flag so that 'small size_t' systems +can select it if necessary. + +Error detection in some chunks has improved; in particular the iCCP chunk +reader now does pretty complete validation of the basic format. Some bad +profiles that were previously accepted are now accepted with a warning or +rejected, depending upon the png_set_benign_errors() setting, in particular +the very old broken Microsoft/HP 3144-byte sRGB profile. Starting with +libpng-1.6.11, recognizing and checking sRGB profiles can be avoided by +means of + + #if defined(PNG_SKIP_sRGB_CHECK_PROFILE) && \ + defined(PNG_SET_OPTION_SUPPORTED) + png_set_option(png_ptr, PNG_SKIP_sRGB_CHECK_PROFILE, + PNG_OPTION_ON); + #endif + +It's not a good idea to do this if you are using the "simplified API", +which needs to be able to recognize sRGB profiles conveyed via the iCCP +chunk. + +The PNG spec requirement that only grayscale profiles may appear in images +with color type 0 or 4 and that even if the image only contains gray pixels, +only RGB profiles may appear in images with color type 2, 3, or 6, is now +enforced. The sRGB chunk is allowed to appear in images with any color type +and is interpreted by libpng to convey a one-tracer-curve gray profile or a +three-tracer-curve RGB profile as appropriate. + +Prior to libpng-1.6.0 a warning would be issued if the iTXt chunk contained +an empty language field or an empty translated keyword. Both of these +are allowed by the PNG specification, so these warnings are no longer issued. + +The library now issues an error if the application attempts to set a +transform after it calls png_read_update_info() or if it attempts to call +both png_read_update_info() and png_start_read_image() or to call either +of them more than once. + +The default condition for benign_errors is now to treat benign errors as +warnings while reading and as errors while writing. + +The library now issues a warning if both background processing and RGB to +gray are used when gamma correction happens. As with previous versions of +the library the results are numerically very incorrect in this case. + +There are some minor arithmetic changes in some transforms such as +png_set_background(), that might be detected by certain regression tests. + +Unknown chunk handling has been improved internally, without any API change. +This adds more correct option control of the unknown handling, corrects +a pre-existing bug where the per-chunk 'keep' setting is ignored, and makes +it possible to skip IDAT chunks in the sequential reader. + +The machine-generated configure files are no longer included in branches +libpng16 and later of the GIT repository. They continue to be included +in the tarball releases, however. + +Libpng-1.6.0 through 1.6.2 used the CMF bytes at the beginning of the IDAT +stream to set the size of the sliding window for reading instead of using the +default 32-kbyte sliding window size. It was discovered that there are +hundreds of PNG files in the wild that have incorrect CMF bytes that caused +zlib to issue the "invalid distance too far back" error and reject the file. +Libpng-1.6.3 and later calculate their own safe CMF from the image dimensions, +provide a way to revert to the libpng-1.5.x behavior (ignoring the CMF bytes +and using a 32-kbyte sliding window), by using + + png_set_option(png_ptr, PNG_MAXIMUM_INFLATE_WINDOW, + PNG_OPTION_ON); + +and provide a tool (contrib/tools/pngfix) for rewriting a PNG file while +optimizing the CMF bytes in its IDAT chunk correctly. + +Libpng-1.6.0 and libpng-1.6.1 wrote uncompressed iTXt chunks with the wrong +length, which resulted in PNG files that cannot be read beyond the bad iTXt +chunk. This error was fixed in libpng-1.6.3, and a tool (called +contrib/tools/png-fix-itxt) has been added to the libpng distribution. + +XIII. Detecting libpng The png_get_io_ptr() function has been present since libpng-0.88, has never changed, and is unaffected by conditional compilation macros. It is the @@ -4459,18 +5118,18 @@ libpng version since 0.88. In an autoconf "configure.in" you could use AC_CHECK_LIB(png, png_get_io_ptr, ... -XII. Source code repository +XV. Source code repository Since about February 2009, version 1.2.34, libpng has been under "git" source control. The git repository was built from old libpng-x.y.z.tar.gz files going back to version 0.70. You can access the git repository (read only) at - git://libpng.git.sourceforge.net/gitroot/libpng + git://git.code.sf.net/p/libpng/code -or you can browse it via "gitweb" at +or you can browse it with a web browser by selecting the "code" button at - http://libpng.git.sourceforge.net/git/gitweb.cgi?p=libpng + https://sourceforge.net/projects/libpng Patches can be sent to glennrp at users.sourceforge.net or to png-mng-implement at lists.sourceforge.net or you can upload them to @@ -4483,9 +5142,10 @@ simple verbal discriptions of bug fixes, reported either to the SourceForge bug tracker, to the png-mng-implement at lists.sf.net mailing list, or directly to glennrp. -XIII. Coding style +XV. Coding style -Our coding style is similar to the "Allman" style, with curly +Our coding style is similar to the "Allman" style +(See http://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly braces on separate lines: if (condition) @@ -4548,6 +5208,9 @@ exported functions are marked with PNGAPI: body; } +The return type and decorations are placed on a separate line +ahead of the function name, as illustrated above. + The prototypes for all exported functions appear in png.h, above the comment that says @@ -4562,17 +5225,29 @@ We mark all non-exported functions with "/* PRIVATE */"": } The prototypes for non-exported functions (except for those in -pngtest) appear in -pngpriv.h -above the comment that says +pngtest) appear in pngpriv.h above the comment that says - /* Maintainer: Put new private prototypes here ^ and in libpngpf.3 */ + /* Maintainer: Put new private prototypes here ^ */ To avoid polluting the global namespace, the names of all exported functions and variables begin with "png_", and all publicly visible C preprocessor macros begin with "PNG". We request that applications that use libpng *not* begin any of their own symbols with either of these strings. +We put a space after the "sizeof" operator and we omit the +optional parentheses around its argument when the argument +is an expression, not a type name, and we always enclose the +sizeof operator, with its argument, in parentheses: + + (sizeof (png_uint_32)) + (sizeof array) + +Prior to libpng-1.6.0 we used a "png_sizeof()" macro, formatted as +though it were a function. + +Control keywords if, for, while, and switch are always followed by a space +to distinguish them from function calls, which have no trailing space. + We put a space after each comma and after each semicolon in "for" statements, and we put spaces before and after each C binary operator and after "for" or "while", and before @@ -4583,44 +5258,52 @@ left parenthesis that follows it: for (i = 2; i > 0; --i) y[i] = a(x) + (int)b; -We prefer #ifdef and #ifndef to #if defined() and if !defined() -when there is only one macro being tested. +We prefer #ifdef and #ifndef to #if defined() and #if !defined() +when there is only one macro being tested. We always use parentheses +with "defined". We prefer to express integers that are used as bit masks in hex format, with an even number of lower-case hex digits (e.g., 0x00, 0xff, 0x0100). +We prefer to use underscores in variable names rather than camelCase, except +for a few type names that we inherit from zlib.h. + +We prefer "if (something != 0)" and "if (something == 0)" +over "if (something)" and if "(!something)", respectively. + We do not use the TAB character for indentation in the C sources. Lines do not exceed 80 characters. Other rules can be inferred by inspecting the libpng source. -XIV. Y2K Compliance in libpng +XVI. Y2K Compliance in libpng -March 29, 2012 +March 26, 2015 Since the PNG Development group is an ad-hoc body, we can't make an official declaration. This is your unofficial assurance that libpng from version 0.71 and -upward through 1.5.10 are Y2K compliant. It is my belief that earlier +upward through 1.6.17 are Y2K compliant. It is my belief that earlier versions were also Y2K compliant. -Libpng only has three year fields. One is a 2-byte unsigned integer that -will hold years up to 65535. The other two hold the date in text -format, and will hold years up to 9999. +Libpng only has two year fields. One is a 2-byte unsigned integer +that will hold years up to 65535. The other, which is deprecated, +holds the date in text format, and will hold years up to 9999. The integer is "png_uint_16 year" in png_time_struct. -The strings are - "png_charp time_buffer" in png_struct and - "near_time_buffer", which is a local character string in png.c. +The string is + "char time_buffer[29]" in png_struct. This is no longer used +in libpng-1.6.x and will be removed from libpng-1.7.0. There are seven time-related functions: - png_convert_to_rfc_1123() in png.c - (formerly png_convert_to_rfc_1152() in error) + png_convert_to_rfc_1123_buffer() in png.c + (formerly png_convert_to_rfc_1152() in error, and + also formerly png_convert_to_rfc_1123()) png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c png_convert_from_time_t() in pngwrite.c |