X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c801d85f158c4cba50b588807daabdcbd0ed3853..8f974c520a8733158591891458fda10fae4c3950:/src/png/libpng.3 diff --git a/src/png/libpng.3 b/src/png/libpng.3 index 88d8c9642c..f970736092 100644 --- a/src/png/libpng.3 +++ b/src/png/libpng.3 @@ -1,6 +1,6 @@ -.TH LIBPNG 3 "March 15, 1998" +.TH LIBPNG 3 "January 14, 1999" .SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library +libpng \- Portable Network Graphics (PNG) Reference Library 1.0.3 - January 14, 1999 .SH SYNOPSIS #include @@ -27,14 +27,25 @@ png_structp png_create_read_struct (png_const_charp user_png_ver, voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn); +png_structp png_create_read_struct_2(png_const_charp user_png_ver, +png_voidp error_ptr, png_error_ptr error_fn, png_error_ptr +warn_fn, png_voidp mem_ptr, png_malloc_ptr malloc_fn, +png_free_ptr free_fn) + png_structp png_create_write_struct (png_const_charp user_png_ver, voidp error_ptr, png_error_ptr error_fn, png_error_ptr warn_fn); -void png_debug_free (png_structp png_ptr, png_voidp ptr); +png_structp png_create_write_struct_2(png_const_charp +user_png_ver, png_voidp error_ptr, png_error_ptr error_fn, +png_error_ptr warn_fn, png_voidp mem_ptr, +png_malloc_ptr malloc_fn, png_free_ptr free_fn) + +int png_debug(int level, png_const_charp message) + +int png_debug1(int level, png_const_charp message, p1) -png_voidp png_debug_malloc (png_structp png_ptr, png_uint_32 -size); +int png_debug2(int level, png_const_charp message, p1, p2) void png_destroy_info_struct (png_structp png_ptr, png_infopp info_ptr_ptr); @@ -49,6 +60,8 @@ void png_error (png_structp png_ptr, png_const_charp error); void png_free (png_structp png_ptr, png_voidp ptr); +void png_free_default(png_structp png_ptr, png_voidp ptr) + png_byte png_get_bit_depth (png_structp png_ptr, png_infop info_ptr); @@ -69,6 +82,8 @@ info_ptr); png_byte png_get_compression_type (png_structp png_ptr, png_infop info_ptr); +png_byte png_get_copyright (png_structp png_ptr); + png_voidp png_get_error_ptr (png_structp png_ptr); png_byte png_get_filter_type (png_structp png_ptr, png_infop @@ -77,9 +92,16 @@ info_ptr); png_uint_32 png_get_gAMA (png_structp png_ptr, png_infop info_ptr, double *file_gamma); +png_byte png_get_header_version (png_structp png_ptr); + png_uint_32 png_get_hIST (png_structp png_ptr, png_infop info_ptr, png_uint_16p *hist); +png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop +info_ptr, png_uint_32 *width, png_uint_32 *height, int +*bit_depth, int *color_type, int *interlace_type, int +*compression_type, int *filter_type); + png_uint_32 png_get_image_height (png_structp png_ptr, png_infop info_ptr); @@ -91,10 +113,7 @@ info_ptr); png_voidp png_get_io_ptr (png_structp png_ptr); -png_uint_32 png_get_IHDR (png_structp png_ptr, png_infop -info_ptr, png_uint_32 *width, png_uint_32 *height, int -*bit_depth, int *color_type, int *interlace_type, int -*compression_type, int *filter_type); +png_voidp png_get_mem_ptr(png_structp png_ptr) png_uint_32 png_get_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32 *offset_x, png_uint_32 *offset_y, int @@ -119,6 +138,8 @@ png_voidp png_get_progressive_ptr (png_structp png_ptr); png_uint_32 png_get_PLTE (png_structp png_ptr, png_infop info_ptr, png_colorp *palette, int *num_palette); +png_byte png_get_rgb_to_gray_status (png_structp png_ptr) + png_uint_32 png_get_rowbytes (png_structp png_ptr, png_infop info_ptr); @@ -168,6 +189,9 @@ void png_init_io (png_structp png_ptr, FILE *fp); png_voidp png_malloc (png_structp png_ptr, png_uint_32 size); +png_voidp png_malloc_default(png_structp png_ptr, +png_uint_32 size) + voidp png_memcpy (png_voidp s1, png_voidp s2, png_size_t size); png_voidp png_memcpy_check (png_structp png_ptr, png_voidp s1, @@ -276,6 +300,9 @@ png_uint_32 width, png_uint_32 height, int bit_depth, int color_type, int interlace_type, int compression_type, int filter_type); +void png_set_mem_fn(png_structp png_ptr, png_voidp mem_ptr, +png_malloc_ptr malloc_fn, png_free_ptr free_fn) + void png_set_oFFs (png_structp png_ptr, png_infop info_ptr, png_uint_32 offset_x, png_uint_32 offset_y, int unit_type); @@ -302,12 +329,12 @@ void png_set_read_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr read_data_fn); void png_set_read_status_fn (png_structp png_ptr, png_read_status_ptr - read_row_fn); +read_row_fn); void png_set_read_user_transform_fn (png_structp png_ptr, - png_user_transform_ptr read_user_transform_fn); +png_user_transform_ptr read_user_transform_fn); -void png_set_rgb_to_gray (png_structp png_ptr); +void png_set_rgb_to_gray (png_structp png_ptr, int error_action); void png_set_sBIT (png_structp png_ptr, png_infop info_ptr, png_color_8p sig_bit); @@ -344,10 +371,10 @@ void png_set_write_fn (png_structp png_ptr, png_voidp io_ptr, png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn); void png_set_write_status_fn (png_structp png_ptr, png_write_status_ptr - write_row_fn); +write_row_fn); void png_set_write_user_transform_fn (png_structp png_ptr, - png_user_transform_ptr write_user_transform_fn); +png_user_transform_ptr write_user_transform_fn); int png_sig_cmp (png_bytep sig, png_size_t start, png_size_t num_to_check); @@ -375,7 +402,7 @@ void png_write_destroy_info (png_infop info_ptr); void png_write_end (png_structp png_ptr, png_infop info_ptr); void png_write_flush (png_structp png_ptr); - + void png_write_image (png_structp png_ptr, png_bytepp image); void png_write_info (png_structp png_ptr, png_infop info_ptr); @@ -396,17 +423,17 @@ Following is a copy of the libpng.txt file that accompanies libpng. .SH LIBPNG.TXT libpng.txt - A description on how to use and modify libpng - libpng version 1.0.1 March 15, 1998 + libpng version 1.0.3 - January 14, 1999 Updated and distributed by Glenn Randers-Pehrson - Copyright (c) 1998, Glenn Randers-Pehrson + Copyright (c) 1998, 1999 Glenn Randers-Pehrson For conditions of distribution and use, see copyright notice in png.h. based on: libpng 1.0 beta 6 version 0.96 May 28, 1997 - Updated and distributed by Andreas Dilger + Updated and distributed by Andreas Dilger Copyright (c) 1996, 1997 Andreas Dilger libpng 1.0 beta 2 - version 0.88 January 26, 1996 @@ -436,7 +463,8 @@ as RFC 2083 and as a W3C Recommendation . Some additional chunks are described in the special-purpose public chunks documents at . Other information -about PNG can be found at the PNG home page, . +about PNG, and the latest version of libpng, can be found at the PNG home +page, . Most users will not have to modify the library significantly; advanced users may want to modify it more. All attempts were made to make it as @@ -453,6 +481,8 @@ work to be done (see the TODO file), libpng should cover the majority of the needs of its users. Libpng uses zlib for its compression and decompression of PNG files. +Further information about zlib, and the latest version of zlib, can +be found at the zlib home page, . The zlib compression utility is a general purpose utility that is useful for more than PNG files, and can be used without libpng. See the documentation delivered with zlib for more details. @@ -522,7 +552,7 @@ Customizing libpng. return; } fread(header, 1, number, fp); - is_png = png_check_sig(header, 0, number); + is_png = !png_sig_cmp(header, 0, number); if (!is_png) { return; @@ -539,7 +569,7 @@ be NULL if the default error handlers are to be used). See the section on Changes to Libpng below regarding the old initialization functions. png_structp png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (void *)user_error_ptr, + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, user_error_fn, user_warning_fn); if (!png_ptr) return; @@ -560,12 +590,23 @@ on Changes to Libpng below regarding the old initialization functions. return; } +If you want to use your own memory allocation routines, +define PNG_USER_MEM_SUPPORTED and use +png_create_read_struct_2() instead of png_create_read_struct(): + + png_structp png_ptr = png_create_read_struct_2 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn, (png_voidp) + user_mem_ptr, user_malloc_fn, user_free_fn); + +The error handling routines passed to png_create_read_struct() +and the memory alloc/free routines passed to png_create_struct_2() +are only necessary if you are not using the libpng supplied error +handling and memory alloc/free functions. -The error handling routines passed to png_create_read_struct() are only -necessary if you are not using the libpng supplied error handling -functions. When libpng encounters an error, it expects to longjmp back -to your routine. Therefore, you will need to call setjmp and pass the -jmpbuf field of your png_struct. If you read the file from different +When libpng encounters an error, it expects to longjmp back +to your routine. Therefore, you will need to call setjmp and pass +your png_ptr->jmpbuf. If you read the file from different routines, you will need to update the jmpbuf field every time you enter a new routine that will call a png_ function. @@ -638,7 +679,7 @@ with You must supply the function void read_transform_fn(png_ptr ptr, row_info_ptr - row_info, png_bytep data) + row_info, png_bytep data) See pngtest.c for a working example. Your function will be called after all of the other transformations have been processed. @@ -667,7 +708,7 @@ Functions are used to get the information from the info_ptr: are present. PNG_COLOR_TYPE_GRAY (bit depths 1, 2, 4, 8, 16) - PNG_COLOR_TYPE_GRAY_ALPHA + PNG_COLOR_TYPE_GRAY_ALPHA (bit depths 8, 16) PNG_COLOR_TYPE_PALETTE (bit depths 1, 2, 4, 8) @@ -872,11 +913,14 @@ unless the library has been told to transform it into another format. For example, 4 bit/pixel paletted or grayscale data will be returned 2 pixels/byte with the leftmost pixel in the high-order bits of the byte, unless png_set_packing() is called. 8-bit RGB data will be stored -in RGBRGBRGB format unless png_set_filler() is called to insert filler +in RGB RGB RGB format unless png_set_filler() is called to insert filler bytes, either before or after each RGB triplet. 16-bit RGB data will -be returned RRGGBBRRGGBB, with the most significant byte of the color +be returned RRGGBB RRGGBB, with the most significant byte of the color value first, unless png_set_strip_16() is called to transform it to -regular RGBRGB triplets. +regular RGB RGB triplets, or png_set_filler() is called to insert +filler bytes, either before or after each RRGGBB triplet. Similarly, +8-bit or 16-bit grayscale data can be modified with png_set_filler() +or png_set_strip_16(). The following code transforms grayscale images of less than 8 to 8 bits, changes paletted images to RGB, and adds a full alpha channel if there is @@ -952,7 +996,7 @@ into 4 bytes for windowing systems that need them in this format: PNG_COLOR_TYPE_RGB) png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE); -where "filler" is the number to fill with, and the location is +where "filler" is the 8 or 16-bit number to fill with, and the location is either PNG_FILLER_BEFORE or PNG_FILLER_AFTER, depending upon whether you want the filler before the RGB or after. This transformation does not affect images that already have full alpha channels. @@ -970,22 +1014,77 @@ RGB. This code will do that conversion: color_type == PNG_COLOR_TYPE_GRAY_ALPHA) png_set_gray_to_rgb(png_ptr); +Conversely, you can convert an RGB or RGBA image to grayscale or grayscale +with alpha. This is intended for conversion of images that really are +gray (red == green == blue), so the function simply strips out the red +and blue channels, leaving the green channel in the gray position. + + if (color_type == PNG_COLOR_TYPE_RGB || + color_type == PNG_COLOR_TYPE_RGB_ALPHA) + png_set_rgb_to_gray(png_ptr, error_action, + float red_weight, float green_weight); + + error_action = 1: silently do the conversion + error_action = 2: issue a warning if the original + image has any pixel where + red != green or red != blue + error_action = 3: issue an error and abort the + conversion if the original + image has any pixel where + red != green or red != blue + + red_weight: weight of red component + (NULL -> default 54/256) + green_weight: weight of green component + (NULL -> default 183/256) + +If you have set error_action = 1 or 2, you can +later check whether the image really was gray, after processing +the image rows, with the png_get_rgb_to_gray_status(png_ptr) function. +It will return a png_byte that is zero if the image was gray or +1 if there were any non-gray pixels. bKGD and sBIT data +will be silently converted to grayscale, using the green channel +data, regardless of the error_action setting. + +With 0.0<=red_weight+green_weight<=1.0, +the normalized graylevel is computed: + + int rw = red_weight * 256; + int gw = green_weight * 256; + int bw = 256 - (rw + gw); + gray = (rw*red + gw*green + bw*blue)/256; + +The default values approximate those recommended in the Charles +Poynton's Color FAQ, +Copyright (c) 1998-01-04 Charles Poynton poynton@inforamp.net + + Y = 0.212671 * R + 0.715160 * G + 0.072169 * B + +Libpng approximates this with + + Y = 0.211 * R + 0.715 * G + 0.074 * B + +which can be expressed with integers as + + Y = (54 * R + 183 * G + 19 * B)/256 + +The calculation is done in a linear colorspace, if the image gamma +is known. + If you have a grayscale and you are using png_set_expand() to change to -a higher bit-depth you must indicate if the supplied background gray -is supplied in the original file bit depth (need_expand = 1) or in the -expanded bit depth (need_expand = 0). Similarly, if you are reading -a paletted image, you must indicate if you have supplied the background -as a palette index that needs to be expanded (need_expand = 1). You can -also specify an RGB triplet that isn't in the palette when setting your -background for a paletted image. +a higher bit-depth, you must either supply the background color as a gray +value at the original file bit-depth (need_expand = 1) or else supply the +background color as an RGB triplet at the final, expanded bit depth +(need_expand = 0). Similarly, if you are reading a paletted image, you +must either supply the background color as a palette index (need_expand = 1) +or as an RGB triplet that may or may not be in the palette (need_expand = 0). png_color_16 my_background; png_color_16p image_background; - if (png_get_bKGD(png_ptr, info_ptr, - &image_background)) - png_set_background(png_ptr, image_background), - PNG_BACKGROUND_GAMMA_FILE, 1, 1.0); + if (png_get_bKGD(png_ptr, info_ptr, &image_background)) + png_set_background(png_ptr, image_background, + PNG_BACKGROUND_GAMMA_FILE, 1, 1.0); else png_set_background(png_ptr, &my_background, PNG_BACKGROUND_GAMMA_SCREEN, 0, 1.0); @@ -1031,7 +1130,7 @@ compensation other than the display_gamma is needed (viewing_gamma=1.0). The png_set_gamma() function handles gamma transformations of the data. Pass both the file gamma and the current screen_gamma. If the file does not have a gamma value, you can pass one anyway if you have an idea what -it is (usually 0.50 is a good guess for GIF images on PCs). Note +it is (usually 0.45455 is a good guess for GIF images on PCs). Note that file gammas are inverted from screen gammas. See the discussions on gamma in the PNG specification for an excellent description of what gamma is, and why all applications should support it. It is strongly @@ -1040,7 +1139,7 @@ recommended that PNG viewers support gamma correction. if (png_get_gAMA(png_ptr, info_ptr, &gamma)) png_set_gamma(png_ptr, screen_gamma, gamma); else - png_set_gamma(png_ptr, screen_gamma, 0.50); + 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_dither() @@ -1268,7 +1367,7 @@ png_infop info_ptr; initialize_png_reader() { png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (void *)user_error_ptr, + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, user_error_fn, user_warning_fn); if (!png_ptr) return -1; @@ -1291,7 +1390,9 @@ png_infop info_ptr; to be called when the header info is valid, when each row is completed, and when the image is finished. If you aren't using all functions, - you can specify a NULL parameter. You can use + you can specify NULL parameters. Even when all + three functions are NULL, you need to call + png_set_progressive_read_fn(). You can use any struct as the user_ptr (cast to a void pointer for the function call), and retrieve the pointer from inside the callbacks using the function @@ -1323,21 +1424,21 @@ png_infop info_ptr; of data from the file stream (in order, of course). On machines with segmented memory models machines, don't give it any more than - 64K. The library seems to run fine with sizes + 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 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 - so there. + so there. */ png_process_data(png_ptr, info_ptr, buffer, length); return 0; } /* This function is called (as set by - png_set_progressive_fn() above) when enough data + png_set_progressive_read_fn() above) when enough data has been supplied so all of the header has been read. */ @@ -1387,14 +1488,14 @@ png_infop info_ptr; new_row); /* where old_row is what was displayed for - previous rows. Note that the first pass - (pass == 0, really) will completely cover + 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 initialized. After the first pass (and only for interlaced images), you will have to pass the current row, and the function will combine the old row and the new row. - */ + */ } void @@ -1412,6 +1513,8 @@ png_infop info_ptr; */ } + + .SH IV. Writing Much of this is very similar to reading. However, everything of @@ -1422,7 +1525,7 @@ You will want to do the I/O initialization before you get into libpng, so if it doesn't work, you don't have anything to undo. If you are not using the standard I/O functions, you will need to replace them with custom writing functions. See the discussion under Customizing libpng. - + FILE *fp = fopen(file_name, "wb"); if (!fp) { @@ -1438,7 +1541,7 @@ both "png_ptr"; you can call them anything you like, such as "read_ptr" and "write_ptr". Look at pngtest.c, for example. png_structp png_ptr = png_create_write_struct - (PNG_LIBPNG_VER_STRING, (void *)user_error_ptr, + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, user_error_fn, user_warning_fn); if (!png_ptr) return; @@ -1451,23 +1554,34 @@ both "png_ptr"; you can call them anything you like, such as return; } +If you want to use your own memory allocation routines, +define PNG_USER_MEM_SUPPORTED and use +png_create_write_struct_2() instead of png_create_read_struct(): + + png_structp png_ptr = png_create_write_struct_2 + (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, + user_error_fn, user_warning_fn, (png_voidp) + user_mem_ptr, user_malloc_fn, user_free_fn); + After you have these structures, you will need to set up the error handling. When libpng encounters an error, it expects to longjmp() back to your routine. Therefore, you will need to call -setjmp and pass the jmpbuf field of your png_struct. If you +setjmp() and pass the png_ptr->jmpbuf. If you write the file from different routines, you will need to update the jmpbuf field every time you enter a new routine that will call a png_ function. See your documentation of setjmp/longjmp for your compiler for more information on setjmp/longjmp. See the discussion on libpng error handling in the Customizing Libpng section below for more information on the libpng error handling. - + if (setjmp(png_ptr->jmpbuf)) - { + { png_destroy_write_struct(&png_ptr, &info_ptr); fclose(fp); return; } + ... + return; 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 @@ -1504,11 +1618,11 @@ not calling this function at all, as it has been tuned to deliver a good speed/compression ratio. The second parameter to png_set_filter() is the filter method, for which the only valid value is '0' (as of the October 1996 PNG specification, version 1.0). The third parameter is a -flag that indicates -which filter type(s) are to be tested for each scanline. See the -Compression Library for details on the specific filter types. +flag that indicates which filter type(s) are to be tested for each +scanline. See the Compression Library for details on the specific filter +types. + - /* turn on or off filtering, and/or choose specific filters */ png_set_filter(png_ptr, 0, @@ -1607,7 +1721,7 @@ Some of the more important parts of the png_info are: PNG_SRGB_INTENT_PERCEPTUAL, PNG_SRGB_INTENT_ABSOLUTE, or PNG_SRGB_INTENT_RELATIVE. - + png_set_sRGB_gAMA_and_cHRM(png_ptr, info_ptr, srgb_intent); @@ -1698,7 +1812,7 @@ png_text structure holds a keyword-text value, and a compression type. The compression types have the same valid numbers as the compression types of the image data. Currently, the only valid number is zero. However, you can store text either compressed or uncompressed, unlike -images which always have to be compressed. So if you don't want the +images, which always have to be compressed. So if you don't want the text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE. Until text gets around 1000 bytes, it is not worth compressing it. After the text has been written out to the file, the compression type @@ -1758,7 +1872,7 @@ depending on whether you mean the PNG file, the time the image was created in a non-PNG format, a still photo from which the image was scanned, or possibly the subject matter itself. In order to facilitate machine-readable dates, it is recommended that the "Creation Time" -tEXt chunk use RFC 1123 format dates (e.g. 22 May 1997 18:07:10 GMT"), +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 @@ -1780,8 +1894,9 @@ checks to see if it has data that it can do something with, you should make sure to only enable a transformation if it will be valid for the data. For example, don't swap red and blue on grayscale data. -PNG files store RGB pixels packed into 3 bytes. This code tells -the library to expect input data with 4 bytes per pixel +PNG files store RGB pixels packed into 3 or 6 bytes. This code tells +the library to expand the input data to 4 or 8 bytes per pixel +(or expand 1 or 2-byte grayscale data to 2 or 4 bytes per pixel). png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE); @@ -1799,7 +1914,7 @@ correctly pack the pixels into a single byte: PNG files reduce possible bit depths to 1, 2, 4, 8, and 16. If your data is of another bit depth, you can write an sBIT chunk into the file so that decoders can get the original data if desired. - + /* Set the true bit depth of the image data */ if (color_type & PNG_COLOR_MASK_COLOR) { @@ -1860,7 +1975,7 @@ with You must supply the function void write_transform_fn(png_ptr ptr, row_info_ptr - row_info, png_bytep data) + row_info, png_bytep data) See pngtest.c for a working example. Your function will be called before any of the other transformations have been processed. @@ -1899,11 +2014,11 @@ times, or any of that other stuff necessary with png_write_rows(). where row_pointers is: - png_bytef *row_pointers[height]; + png_byte *row_pointers[height]; You can point to void or char or whatever you use for pixels. -If you can't want to write the whole image at once, you can +If you don't want to write the whole image at once, you can use png_write_rows() instead. If the file is not interlaced, this is simple: @@ -1975,7 +2090,7 @@ The second deals with more complicated things like adding new chunks, adding new transformations, and generally changing how libpng works. All of the memory allocation, input/output, and error handling in libpng -goes through callbacks which are user settable. The default routines are +goes through callbacks that are user settable. The default routines are in pngmem.c, pngrio.c, pngwio.c, and pngerror.c respectively. To change these functions, call the appropriate png_set_???_fn() function. @@ -1997,14 +2112,15 @@ time, instead of calling the png_init_io() function. These functions also provide a void pointer that can be retrieved via the function png_get_io_ptr(). For example: - png_set_read_fn(png_structp png_ptr, - voidp io_ptr, png_rw_ptr read_data_fn) + png_set_read_fn(png_structp read_ptr, + voidp read_io_ptr, png_rw_ptr read_data_fn) - png_set_write_fn(png_structp png_ptr, - voidp io_ptr, png_rw_ptr write_data_fn, + png_set_write_fn(png_structp write_ptr, + voidp write_io_ptr, png_rw_ptr write_data_fn, png_flush_ptr output_flush_fn); - voidp io_ptr = png_get_io_ptr(png_ptr); + voidp read_io_ptr = png_get_io_ptr(read_ptr); + voidp write_io_ptr = png_get_io_ptr(write_ptr); The replacement I/O functions should have prototypes as follows: @@ -2083,7 +2199,7 @@ won't be accessible. So limit zlib and libpng to 64K by defining MAXSEG_64K. Configuring for DOS: -For DOS users which only have access to the lower 640K, you will +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. @@ -2095,7 +2211,7 @@ 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 row's of data are defined as png_bytepp which is a +note that the row's of data are defined as png_bytepp, which is an unsigned char far * far *. Configuring for gui/windowing platforms: @@ -2155,8 +2271,8 @@ can call one of these functions. The selection and configuration of row filters can have a significant impact on the size and encoding speed and a somewhat lesser impact on the decoding speed of an image. Filtering is enabled by default for RGB and grayscale -images (with and without alpha), and for 8-bit paletted images, but -not for paletted images with bit depths less than 8 bits/pixel. +images (with and without alpha), but not for paletted images nor +for any images with bit depths less than 8 bits/pixel. The 'method' parameter sets the main filtering method, which is currently only '0' in the PNG 1.0 specification. The 'filters' @@ -2191,10 +2307,10 @@ by telling it the relative computational costs of the filters. PNG_FILTER_SELECTION_WEIGHTED, 3, weights, costs); -The weights are multiplying factors which indicate to libpng that row -should be the same for successive rows unless another row filter is that -many times better than the previous filter. In the above example, if -the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a +The weights are multiplying factors that indicate to libpng that the +row filter should be the same for successive rows unless another row filter +is that many times better than the previous filter. In the above example, +if the previous 3 filters were SUB, SUB, NONE, the SUB filter could have a "sum of absolute differences" 1.5 x 1.3 times higher than other filters and still be chosen, while the NONE filter could have a sum 1.1 times higher than other filters and still be chosen. Unspecified weights are @@ -2217,19 +2333,23 @@ 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 an ability, you can change the #define to #undef -before recompiling libpng and save yourself code and data space. -You can also turn a number of them off en masse with a compiler directive -that defines PNG_READ[or WRITE]_TRANSFORMS_NOT_SUPPORTED, or -PNG_READ[or WRITE]_ANCILLARY_CHUNKS_NOT_SUPPORTED, or all four, +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_. + +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_READ[or WRITE]_TRANSFORMS_NOT_SUPPORTED directives disable +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 [except for sPLT]. -Use of the PNG_READ[or WRITE]_ANCILLARY_CHUNKS_NOT_SUPPORTED directive +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_PROGRESSIVE_READ_NOT_SUPPORTED (don't confuse +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 @@ -2245,10 +2365,46 @@ 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 which are actually used will be loaded into memory. +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 +printout. Set it to an integer value in the range 0 to 3. Higher +numbers result in increasing amounts of debugging information. The +information is printed to the "stderr" file, unless another file +name is specified in the PNG_DEBUG_FILE macro definition. + +When PNG_DEBUG > 0, the following functions (macros) become available: + + png_debug(level, message) + png_debug1(level, message, p1) + png_debug2(level, message, p1, p2) + +in which "level" is compared to PNG_DEBUG to decide whether to print +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); +is expanded to -Changes to Libpng from version 0.88 + if(PNG_DEBUG > 2) + fprintf(PNG_DEBUG_FILE, "foo=%d\n", foo); + +When PNG_DEBUG is defined but is zero, the macros aren't defined, but you +can still use PNG_DEBUG to control your own debugging: + + #ifdef PNG_DEBUG + fprintf(stderr, ... + #endif + +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. + +.SH VI. 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 @@ -2274,13 +2430,65 @@ allocating and freeing the png_struct for each image read. Setting the error callbacks via png_set_message_fn() before png_read_init() as was suggested in libpng-0.88 is no longer supported -because this caused applications which do not use custom error functions +because this caused applications that do not use custom error functions to fail if the png_ptr was not initialized to zero. It is still possible to set the error callbacks AFTER png_read_init(), or to change them with 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. +.SH VII. Y2K Compliance in libpng + +January 13, 1999 + +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.81 and +upward 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. + +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. + +There are seven time-related functions: + + png_convert_to_rfc_1123() in png.c + (formerly png_convert_to_rfc_1152() in error) + png_convert_from_struct_tm() in pngwrite.c, called in pngwrite.c + png_convert_from_time_t() in pngwrite.c + png_get_tIME() in pngget.c + png_handle_tIME() in pngrutil.c, called in pngread.c + png_set_tIME() in pngset.c + png_write_tIME() in pngwutil.c, called in pngwrite.c + +All appear to handle dates properly in a Y2K environment. The +png_convert_from_time_t() function calls gmtime() to convert from system +clock time, which returns (year - 1900), which we properly convert to +the full 4-digit year. There is a possibility that applications using +libpng are not passing 4-digit years into the png_convert_to_rfc_1123() +function, or incorrectly passing only a 2-digit year instead of +"year - 1900" into the png_convert_from_struct_tm() function, but this +is not under our control. The libpng documentation has always stated +that it works with 4-digit years, and the APIs have been documented as +such. + +The tIME chunk itself is also Y2K compliant. It uses a 2-byte unsigned +integer to hold the year, and can hold years as large as 65535. + + + Glenn Randers-Pehrson + libpng maintainer + PNG Development Group + .SH NOTE Note about libpng version numbers: @@ -2366,7 +2574,7 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.0.1 March 15, 1998: +Libpng version 1.0.3 - January 14, 1999: Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn Randers-Pehrson (randeg@alumni.rpi.edu). @@ -2376,6 +2584,10 @@ Supported by the PNG development group .SH COPYRIGHT NOTICE: +Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc. +Copyright (c) 1996, 1997 Andreas Dilger +Copyright (c) 1998, 1999 Glenn Randers-Pehrson + The PNG Reference Library (libpng) is supplied "AS IS". The Contributing Authors and Group 42, Inc. disclaim all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of