From f9ea017839ead14169ed49c77edf0d1b4f592963 Mon Sep 17 00:00:00 2001 From: dartraiden Date: Thu, 19 Jul 2018 16:22:00 +0300 Subject: Remove useless docs --- libs/freeimage/src/LibPNG/CHANGES | 6051 -------------- libs/freeimage/src/LibPNG/INSTALL | 465 -- libs/freeimage/src/LibPNG/README | 222 - libs/freeimage/src/LibPNG/TODO | 30 - libs/freeimage/src/LibPNG/libpng-manual.txt | 5464 ------------- libs/liblua/docs/contents.html | 619 -- libs/liblua/docs/index.css | 21 - libs/liblua/docs/manual.css | 21 - libs/liblua/docs/manual.html | 10982 -------------------------- 9 files changed, 23875 deletions(-) delete mode 100644 libs/freeimage/src/LibPNG/CHANGES delete mode 100644 libs/freeimage/src/LibPNG/INSTALL delete mode 100644 libs/freeimage/src/LibPNG/README delete mode 100644 libs/freeimage/src/LibPNG/TODO delete mode 100644 libs/freeimage/src/LibPNG/libpng-manual.txt delete mode 100644 libs/liblua/docs/contents.html delete mode 100644 libs/liblua/docs/index.css delete mode 100644 libs/liblua/docs/manual.css delete mode 100644 libs/liblua/docs/manual.html diff --git a/libs/freeimage/src/LibPNG/CHANGES b/libs/freeimage/src/LibPNG/CHANGES deleted file mode 100644 index 4b82118910..0000000000 --- a/libs/freeimage/src/LibPNG/CHANGES +++ /dev/null @@ -1,6051 +0,0 @@ -#if 0 -CHANGES - changes for libpng - -version 0.1 [March 29, 1995] - initial work-in-progress release - -version 0.2 [April 1, 1995] - added reader into png.h - fixed small problems in stub file - -version 0.3 [April 8, 1995] - added pull reader - split up pngwrite.c to several files - added pnglib.txt - added example.c - cleaned up writer, adding a few new transformations - fixed some bugs in writer - interfaced with zlib 0.5 - added K&R support - added check for 64 KB blocks for 16 bit machines - -version 0.4 [April 26, 1995] - cleaned up code and commented code - simplified time handling into png_time - created png_color_16 and png_color_8 to handle color needs - cleaned up color type defines - fixed various bugs - made various names more consistent - interfaced with zlib 0.71 - cleaned up zTXt reader and writer (using zlib's Reset functions) - split transformations into pngrtran.c and pngwtran.c - -version 0.5 [April 30, 1995] - interfaced with zlib 0.8 - fixed many reading and writing bugs - saved using 3 spaces instead of tabs - -version 0.6 [May 1, 1995] - first beta release - added png_large_malloc() and png_large_free() - added png_size_t - cleaned up some compiler warnings - added png_start_read_image() - -version 0.7 [June 24, 1995] - cleaned up lots of bugs - finished dithering and other stuff - added test program - changed name from pnglib to libpng - -version 0.71 [June 26, 1995] - changed pngtest.png for zlib 0.93 - fixed error in libpng.txt and example.c - -version 0.8 [August 20, 1995] - cleaned up some bugs - added png_set_filler() - split up pngstub.c into pngmem.c, pngio.c, and pngerror.c - added #define's to remove unwanted code - moved png_info_init() to png.c - added old_size into png_realloc() - added functions to manually set filtering and compression info - changed compression parameters based on image type - optimized filter selection code - added version info - changed external functions passing floats to doubles (k&r problems?) - put all the configurable stuff in pngconf.h - enabled png_set_shift to work with paletted images on read - added png_read_update_info() - updates info structure with transformations - -Version 0.81 [August, 1995] - incorporated Tim Wegner's medium model code (thanks, Tim) - -Version 0.82 [September, 1995] - [unspecified changes] - -Version 0.85 [December, 1995] - added more medium model code (almost everything's a far) - added i/o, error, and memory callback functions - fixed some bugs (16-bit, 4-bit interlaced, etc.) - added first run progressive reader (barely tested) - -Version 0.86 [January, 1996] - fixed bugs - improved documentation - -Version 0.87 [January, 1996] - fixed medium model bugs - fixed other bugs introduced in 0.85 and 0.86 - added some minor documentation - -Version 0.88 [January, 1996] - fixed progressive bugs - replaced tabs with spaces - cleaned up documentation - added callbacks for read/write and warning/error functions - -Version 0.89 [June 5, 1996] - Added new initialization API to make libpng work better with shared libs - we now have png_create_read_struct(), png_create_write_struct(), - png_create_info_struct(), png_destroy_read_struct(), and - png_destroy_write_struct() instead of the separate calls to - malloc and png_read_init(), png_info_init(), and png_write_init() - Changed warning/error callback functions to fix bug - this means you - should use the new initialization API if you were using the old - png_set_message_fn() calls, and that the old API no longer exists - so that people are aware that they need to change their code - Changed filter selection API to allow selection of multiple filters - since it didn't work in previous versions of libpng anyways - Optimized filter selection code - Fixed png_set_background() to allow using an arbitrary RGB color for - paletted images - Fixed gamma and background correction for paletted images, so - png_correct_palette is not needed unless you are correcting an - external palette (you will need to #define PNG_CORRECT_PALETTE_SUPPORTED - in pngconf.h) - if nobody uses this, it may disappear in the future. - Fixed bug with Borland 64K memory allocation (Alexander Lehmann) - Fixed bug in interlace handling (Smarasderagd, I think) - Added more error checking for writing and image to reduce invalid files - Separated read and write functions so that they won't both be linked - into a binary when only reading or writing functionality is used - New pngtest image also has interlacing and zTXt - Updated documentation to reflect new API - -Version 0.89c [June 17, 1996] - Bug fixes. - -Version 0.90 [January, 1997] - Made CRC errors/warnings on critical and ancillary chunks configurable - libpng will use the zlib CRC routines by (compile-time) default - Changed DOS small/medium model memory support - needs zlib 1.04 (Tim Wegner) - Added external C++ wrapper statements to png.h (Gilles Dauphin) - Allow PNG file to be read when some or all of file signature has already - been read from the beginning of the stream. ****This affects the size - of info_struct and invalidates all programs that use a shared libpng**** - Fixed png_filler() declarations - Fixed? background color conversions - Fixed order of error function pointers to match documentation - Current chunk name is now available in png_struct to reduce the number - of nearly identical error messages (will simplify multi-lingual - support when available) - Try to get ready for unknown-chunk callback functions: - - previously read critical chunks are flagged, so the chunk handling - routines can determine if the chunk is in the right place - - all chunk handling routines have the same prototypes, so we will - be able to handle all chunks via a callback mechanism - Try to fix Linux "setjmp" buffer size problems - Removed png_large_malloc, png_large_free, and png_realloc functions. - -Version 0.95 [March, 1997] - Fixed bug in pngwutil.c allocating "up_row" twice and "avg_row" never - Fixed bug in PNG file signature compares when start != 0 - Changed parameter type of png_set_filler(...filler...) from png_byte - to png_uint_32 - Added test for MACOS to ensure that both math.h and fp.h are not #included - Added macros for libpng to be compiled as a Windows DLL (Andreas Kupries) - Added "packswap" transformation, which changes the endianness of - packed-pixel bytes (Kevin Bracey) - Added "strip_alpha" transformation, which removes the alpha channel of - input images without using it (not necessarily a good idea) - Added "swap_alpha" transformation, which puts the alpha channel in front - of the color bytes instead of after - Removed all implicit variable tests which assume NULL == 0 (I think) - Changed several variables to "png_size_t" to show 16/32-bit limitations - Added new pCAL chunk read/write support - Added experimental filter selection weighting (Greg Roelofs) - Removed old png_set_rgbx() and png_set_xrgb() functions that have been - obsolete for about 2 years now (use png_set_filler() instead) - Added macros to read 16- and 32-bit ints directly from buffer, to be - used only on those systems that support it (namely PowerPC and 680x0) - With some testing, this may become the default for MACOS/PPC systems. - Only calculate CRC on data if we are going to use it - Added macros for zTXt compression type PNG_zTXt_COMPRESSION_??? - Added macros for simple libpng debugging output selectable at compile time - Removed PNG_READ_END_MODE in progressive reader (Smarasderagd) - More description of info_struct in libpng.txt and png.h - More instructions in example.c - More chunk types tested in pngtest.c - Renamed pngrcb.c to pngset.c, and all png_read_ functions to be - png_set_. We now have corresponding png_get_ - functions in pngget.c to get information in info_ptr. This isolates - the application from the internal organization of png_info_struct - (good for shared library implementations). - -Version 0.96 [May, 1997] - Fixed serious bug with < 8bpp images introduced in 0.95 - Fixed 256-color transparency bug (Greg Roelofs) - Fixed up documentation (Greg Roelofs, Laszlo Nyul) - Fixed "error" in pngconf.h for Linux setjmp() behavior - Fixed DOS medium model support (Tim Wegner) - Fixed png_check_keyword() for case with error in static string text - Added read of CRC after IEND chunk for embedded PNGs (Laszlo Nyul) - Added typecasts to quiet compiler errors - Added more debugging info - -Version 0.97 [January, 1998] - Removed PNG_USE_OWN_CRC capability - Relocated png_set_crc_action from pngrutil.c to pngrtran.c - Fixed typecasts of "new_key", etc. (Andreas Dilger) - Added RFC 1152 [sic] date support - Fixed bug in gamma handling of 4-bit grayscale - Added 2-bit grayscale gamma handling (Glenn R-P) - Added more typecasts. 65536L becomes (png_uint_32)65536L, etc. (Glenn R-P) - Minor corrections in libpng.txt - Added simple sRGB support (Glenn R-P) - Easier conditional compiling, e.g., - define PNG_READ/WRITE_NOT_FULLY_SUPPORTED; - all configurable options can be selected from command-line instead - of having to edit pngconf.h (Glenn R-P) - Fixed memory leak in pngwrite.c (free info_ptr->text) (Glenn R-P) - Added more conditions for png_do_background, to avoid changing - black pixels to background when a background is supplied and - no pixels are transparent - Repaired PNG_NO_STDIO behavior - Tested NODIV support and made it default behavior (Greg Roelofs) - Added "-m" option and PNGTEST_DEBUG_MEMORY to pngtest (John Bowler) - Regularized version numbering scheme and bumped shared-library major - version number to 2 to avoid problems with libpng 0.89 apps - (Greg Roelofs) - -Version 0.98 [January, 1998] - Cleaned up some typos in libpng.txt and in code documentation - Fixed memory leaks in pCAL chunk processing (Glenn R-P and John Bowler) - Cosmetic change "display_gamma" to "screen_gamma" in pngrtran.c - Changed recommendation about file_gamma for PC images to .51 from .45, - in example.c and libpng.txt, added comments to distinguish between - screen_gamma, viewing_gamma, and display_gamma. - Changed all references to RFC1152 to read RFC1123 and changed the - PNG_TIME_RFC1152_SUPPORTED macro to PNG_TIME_RFC1123_SUPPORTED - Added png_invert_alpha capability (Glenn R-P -- suggestion by Jon Vincent) - Changed srgb_intent from png_byte to int to avoid compiler bugs - -Version 0.99 [January 30, 1998] - Free info_ptr->text instead of end_info_ptr->text in pngread.c (John Bowler) - Fixed a longstanding "packswap" bug in pngtrans.c - Fixed some inconsistencies in pngconf.h that prevented compiling with - PNG_READ_GAMMA_SUPPORTED and PNG_READ_hIST_SUPPORTED undefined - Fixed some typos and made other minor rearrangement of libpng.txt (Andreas) - Changed recommendation about file_gamma for PC images to .50 from .51 in - example.c and libpng.txt, and changed file_gamma for sRGB images to .45 - Added a number of functions to access information from the png structure - png_get_image_height(), etc. (Glenn R-P, suggestion by Brad Pettit) - Added TARGET_MACOS similar to zlib-1.0.8 - Define PNG_ALWAYS_EXTERN when __MWERKS__ && WIN32 are defined - Added type casting to all png_malloc() function calls - -Version 0.99a [January 31, 1998] - Added type casts and parentheses to all returns that return a value.(Tim W.) - -Version 0.99b [February 4, 1998] - Added type cast png_uint_32 on malloc function calls where needed. - Changed type of num_hist from png_uint_32 to int (same as num_palette). - Added checks for rowbytes overflow, in case png_size_t is less than 32 bits. - Renamed makefile.elf to makefile.lnx. - -Version 0.99c [February 7, 1998] - More type casting. Removed erroneous overflow test in pngmem.c. - Added png_buffered_memcpy() and png_buffered_memset(), apply them to rowbytes. - Added UNIX manual pages libpng.3 (incorporating libpng.txt) and png.5. - -Version 0.99d [February 11, 1998] - Renamed "far_to_near()" "png_far_to_near()" - Revised libpng.3 - Version 99c "buffered" operations didn't work as intended. Replaced them - with png_memcpy_check() and png_memset_check(). - Added many "if (png_ptr == NULL) return" to quell compiler warnings about - unused png_ptr, mostly in pngget.c and pngset.c. - Check for overlength tRNS chunk present when indexed-color PLTE is read. - Cleaned up spelling errors in libpng.3/libpng.txt - Corrected a problem with png_get_tRNS() which returned undefined trans array - -Version 0.99e [February 28, 1998] - Corrected png_get_tRNS() again. - Add parentheses for easier reading of pngget.c, fixed "||" should be "&&". - Touched up example.c to make more of it compileable, although the entire - file still can't be compiled (Willem van Schaik) - Fixed a bug in png_do_shift() (Bryan Tsai) - Added a space in png.h prototype for png_write_chunk_start() - Replaced pngtest.png with one created with zlib 1.1.1 - Changed pngtest to report PASS even when file size is different (Jean-loup G.) - Corrected some logic errors in png_do_invert_alpha() (Chris Patterson) - -Version 0.99f [March 5, 1998] - Corrected a bug in pngpread() introduced in version 99c (Kevin Bracey) - Moved makefiles into a "scripts" directory, and added INSTALL instruction file - Added makefile.os2 and pngos2.def (A. Zabolotny) and makefile.s2x (W. Sebok) - Added pointers to "note on libpng versions" in makefile.lnx and README - Added row callback feature when reading and writing nonprogressive rows - and added a test of this feature in pngtest.c - Added user transform callbacks, with test of the feature in pngtest.c - -Version 0.99g [March 6, 1998, morning] - Minor changes to pngtest.c to suppress compiler warnings. - Removed "beta" language from documentation. - -Version 0.99h [March 6, 1998, evening] - Minor changes to previous minor changes to pngtest.c - Changed PNG_READ_NOT_FULLY_SUPPORTED to PNG_READ_TRANSFORMS_NOT_SUPPORTED - and added PNG_PROGRESSIVE_READ_NOT_SUPPORTED macro - Added user transform capability - -Version 1.00 [March 7, 1998] - Changed several typedefs in pngrutil.c - Added makefile.wat (Pawel Mrochen), updated makefile.tc3 (Willem van Schaik) - Replaced "while(1)" with "for(;;)" - Added PNGARG() to prototypes in pngtest.c and removed some prototypes - Updated some of the makefiles (Tom Lane) - Changed some typedefs (s_start, etc.) in pngrutil.c - Fixed dimensions of "short_months" array in pngwrite.c - Replaced ansi2knr.c with the one from jpeg-v6 - -Version 1.0.0 [March 8, 1998] - Changed name from 1.00 to 1.0.0 (Adam Costello) - Added smakefile.ppc (with SCOPTIONS.ppc) for Amiga PPC (Andreas Kleinert) - -Version 1.0.0a [March 9, 1998] - Fixed three bugs in pngrtran.c to make gamma+background handling consistent - (Greg Roelofs) - Changed format of the PNG_LIBPNG_VER integer to xyyzz instead of xyz - for major, minor, and bugfix releases. This is 10001. (Adam Costello, - Tom Lane) - Make months range from 1-12 in png_convert_to_rfc1123 - -Version 1.0.0b [March 13, 1998] - Quieted compiler complaints about two empty "for" loops in pngrutil.c - Minor changes to makefile.s2x - Removed #ifdef/#endif around a png_free() in pngread.c - -Version 1.0.1 [March 14, 1998] - Changed makefile.s2x to reduce security risk of using a relative pathname - Fixed some typos in the documentation (Greg). - Fixed a problem with value of "channels" returned by png_read_update_info() - -Version 1.0.1a [April 21, 1998] - Optimized Paeth calculations by replacing abs() function calls with intrinsics - plus other loop optimizations. Improves avg decoding speed by about 20%. - Commented out i386istic "align" compiler flags in makefile.lnx. - Reduced the default warning level in some makefiles, to make them consistent. - Removed references to IJG and JPEG in the ansi2knr.c copyright statement. - Fixed a bug in png_do_strip_filler with XXRRGGBB => RRGGBB transformation. - Added grayscale and 16-bit capability to png_do_read_filler(). - Fixed a bug in pngset.c, introduced in version 0.99c, that sets rowbytes - too large when writing an image with bit_depth < 8 (Bob Dellaca). - Corrected some bugs in the experimental weighted filtering heuristics. - Moved a misplaced pngrutil code block that truncates tRNS if it has more - than num_palette entries -- test was done before num_palette was defined. - Fixed a png_convert_to_rfc1123() bug that converts day 31 to 0 (Steve Eddins). - Changed compiler flags in makefile.wat for better optimization - (Pawel Mrochen). - -Version 1.0.1b [May 2, 1998] - Relocated png_do_gray_to_rgb() within png_do_read_transformations() (Greg). - Relocated the png_composite macros from pngrtran.c to png.h (Greg). - Added makefile.sco (contributed by Mike Hopkirk). - Fixed two bugs (missing definitions of "istop") introduced in libpng-1.0.1a. - Fixed a bug in pngrtran.c that would set channels=5 under some circumstances. - More work on the Paeth-filtering, achieving imperceptible speedup - (A Kleinert). - More work on loop optimization which may help when compiled with C++ - compilers. - Added warnings when people try to use transforms they've defined out. - Collapsed 4 "i" and "c" loops into single "i" loops in pngrtran and pngwtran. - Revised paragraph about png_set_expand() in libpng.txt and libpng.3 (Greg) - -Version 1.0.1c [May 11, 1998] - Fixed a bug in pngrtran.c (introduced in libpng-1.0.1a) where the masks for - filler bytes should have been 0xff instead of 0xf. - Added max_pixel_depth=32 in pngrutil.c when using FILLER with palette images. - Moved PNG_WRITE_WEIGHTED_FILTER_SUPPORTED and PNG_WRITE_FLUSH_SUPPORTED - out of the PNG_WRITE_TRANSFORMS_NOT_SUPPORTED block of pngconf.h - Added "PNG_NO_WRITE_TRANSFORMS" etc., as alternatives for *_NOT_SUPPORTED, - for consistency, in pngconf.h - Added individual "ifndef PNG_NO_[CAPABILITY]" in pngconf.h to make it easier - to remove unwanted capabilities via the compile line - Made some corrections to grammar (which, it's) in documentation (Greg). - Corrected example.c, use of row_pointers in png_write_image(). - -Version 1.0.1d [May 24, 1998] - Corrected several statements that used side effects illegally in pngrutil.c - and pngtrans.c, that were introduced in version 1.0.1b - Revised png_read_rows() to avoid repeated if-testing for NULL (A Kleinert) - More corrections to example.c, use of row_pointers in png_write_image() - and png_read_rows(). - Added pngdll.mak and pngdef.pas to scripts directory, contributed by - Bob Dellaca, to make a png32bd.dll with Borland C++ 4.5 - Fixed error in example.c with png_set_text: num_text is 3, not 2 (Guido V.) - Changed several loops from count-down to count-up, for consistency. - -Version 1.0.1e [June 6, 1998] - Revised libpng.txt and libpng.3 description of png_set_read|write_fn(), and - added warnings when people try to set png_read_fn and png_write_fn in - the same structure. - Added a test such that png_do_gamma will be done when num_trans==0 - for truecolor images that have defined a background. This corrects an - error that was introduced in libpng-0.90 that can cause gamma processing - to be skipped. - Added tests in png.h to include "trans" and "trans_values" in structures - when PNG_READ_BACKGROUND_SUPPORTED or PNG_READ_EXPAND_SUPPORTED is defined. - Add png_free(png_ptr->time_buffer) in png_destroy_read_struct() - Moved png_convert_to_rfc_1123() from pngwrite.c to png.c - Added capability for user-provided malloc_fn() and free_fn() functions, - and revised pngtest.c to demonstrate their use, replacing the - PNGTEST_DEBUG_MEM feature. - Added makefile.w32, for Microsoft C++ 4.0 and later (Tim Wegner). - -Version 1.0.2 [June 14, 1998] - Fixed two bugs in makefile.bor . - -Version 1.0.2a [December 30, 1998] - Replaced and extended code that was removed from png_set_filler() in 1.0.1a. - Fixed a bug in png_do_filler() that made it fail to write filler bytes in - the left-most pixel of each row (Kevin Bracey). - Changed "static pngcharp tIME_string" to "static char tIME_string[30]" - in pngtest.c (Duncan Simpson). - Fixed a bug in pngtest.c that caused pngtest to try to write a tIME chunk - even when no tIME chunk was present in the source file. - Fixed a problem in pngrutil.c: gray_to_rgb didn't always work with 16-bit. - Fixed a problem in png_read_push_finish_row(), which would not skip some - passes that it should skip, for images that are less than 3 pixels high. - Interchanged the order of calls to png_do_swap() and png_do_shift() - in pngwtran.c (John Cromer). - Added #ifdef PNG_DEBUG/#endif surrounding use of PNG_DEBUG in png.h . - Changed "bad adaptive filter type" from error to warning in pngrutil.c . - Fixed a documentation error about default filtering with 8-bit indexed-color. - Separated the PNG_NO_STDIO macro into PNG_NO_STDIO and PNG_NO_CONSOLE_IO - (L. Peter Deutsch). - Added png_set_rgb_to_gray() and png_get_rgb_to_gray_status() functions. - Added png_get_copyright() and png_get_header_version() functions. - Revised comments on png_set_progressive_read_fn() in libpng.txt and example.c - Added information about debugging in libpng.txt and libpng.3 . - Changed "ln -sf" to "ln -s -f" in makefile.s2x, makefile.lnx, and - makefile.sco. - Removed lines after Dynamic Dependencies" in makefile.aco . - Revised makefile.dec to make a shared library (Jeremie Petit). - Removed trailing blanks from all files. - -Version 1.0.2a [January 6, 1999] - Removed misplaced #endif and #ifdef PNG_NO_EXTERN near the end of png.h - Added "if" tests to silence complaints about unused png_ptr in png.h and png.c - Changed "check_if_png" function in example.c to return true (nonzero) if PNG. - Changed libpng.txt to demonstrate png_sig_cmp() instead of png_check_sig() - which is obsolete. - -Version 1.0.3 [January 14, 1999] - Added makefile.hux, for Hewlett Packard HPUX 10.20 and 11.00 (Jim Rice) - Added a statement of Y2K compliance in png.h, libpng.3, and Y2KINFO. - -Version 1.0.3a [August 12, 1999] - Added check for PNG_READ_INTERLACE_SUPPORTED in pngread.c; issue a warning - if an attempt is made to read an interlaced image when it's not supported. - Added check if png_ptr->trans is defined before freeing it in pngread.c - Modified the Y2K statement to include versions back to version 0.71 - Fixed a bug in the check for valid IHDR bit_depth/color_types in pngrutil.c - Modified makefile.wat (added -zp8 flag, ".symbolic", changed some comments) - Replaced leading blanks with tab characters in makefile.hux - Changed "dworkin.wustl.edu" to "ccrc.wustl.edu" in various documents. - Changed (float)red and (float)green to (double)red, (double)green - in png_set_rgb_to_gray() to avoid "promotion" problems in AIX. - Fixed a bug in pngconf.h that omitted when PNG_DEBUG==0 (K Bracey). - Reformatted libpng.3 and libpngpf.3 with proper fonts (script by J. vanZandt). - Updated documentation to refer to the PNG-1.2 specification. - Removed ansi2knr.c and left pointers to the latest source for ansi2knr.c - in makefile.knr, INSTALL, and README (L. Peter Deutsch) - Fixed bugs in calculation of the length of rowbytes when adding alpha - channels to 16-bit images, in pngrtran.c (Chris Nokleberg) - Added function png_set_user_transform_info() to store user_transform_ptr, - user_depth, and user_channels into the png_struct, and a function - png_get_user_transform_ptr() to retrieve the pointer (Chris Nokleberg) - Added function png_set_empty_plte_permitted() to make libpng useable - in MNG applications. - Corrected the typedef for png_free_ptr in png.h (Jesse Jones). - Correct gamma with srgb is 45455 instead of 45000 in pngrutil.c, to be - consistent with PNG-1.2, and allow variance of 500 before complaining. - Added assembler code contributed by Intel in file pngvcrd.c and modified - makefile.w32 to use it (Nirav Chhatrapati, INTEL Corporation, - Gilles Vollant) - Changed "ln -s -f" to "ln -f -s" in the makefiles to make Solaris happy. - Added some aliases for png_set_expand() in pngrtran.c, namely - png_set_expand_PLTE(), png_set_expand_depth(), and png_set_expand_tRNS() - (Greg Roelofs, in "PNG: The Definitive Guide"). - Added makefile.beo for BEOS on X86, contributed by Sander Stok. - -Version 1.0.3b [August 26, 1999] - Replaced 2147483647L several places with PNG_MAX_UINT macro, defined in png.h - Changed leading blanks to tabs in all makefiles. - Define PNG_USE_PNGVCRD in makefile.w32, to get MMX assembler code. - Made alternate versions of png_set_expand() in pngrtran.c, namely - png_set_gray_1_2_4_to_8, png_set_palette_to_rgb, and png_set_tRNS_to_alpha - (Greg Roelofs, in "PNG: The Definitive Guide"). Deleted the 1.0.3a aliases. - Relocated start of 'extern "C"' block in png.h so it doesn't include pngconf.h - Revised calculation of num_blocks in pngmem.c to avoid a potentially - negative shift distance, whose results are undefined in the C language. - Added a check in pngset.c to prevent writing multiple tIME chunks. - Added a check in pngwrite.c to detect invalid small window_bits sizes. - -Version 1.0.3d [September 4, 1999] - Fixed type casting of igamma in pngrutil.c - Added new png_expand functions to scripts/pngdef.pas and pngos2.def - Added a demo read_user_transform_fn that examines the row filters in pngtest.c - -Version 1.0.4 [September 24, 1999, not distributed publicly] - Define PNG_ALWAYS_EXTERN in pngconf.h if __STDC__ is defined - Delete #define PNG_INTERNAL and include "png.h" from pngasmrd.h - Made several minor corrections to pngtest.c - Renamed the makefiles with longer but more user friendly extensions. - Copied the PNG copyright and license to a separate LICENSE file. - Revised documentation, png.h, and example.c to remove reference to - "viewing_gamma" which no longer appears in the PNG specification. - Revised pngvcrd.c to use MMX code for interlacing only on the final pass. - Updated pngvcrd.c to use the faster C filter algorithms from libpng-1.0.1a - Split makefile.win32vc into two versions, makefile.vcawin32 (uses MMX - assembler code) and makefile.vcwin32 (doesn't). - Added a CPU timing report to pngtest.c (enabled by defining PNGTEST_TIMING) - Added a copy of pngnow.png to the distribution. - -Version 1.0.4a [September 25, 1999] - Increase max_pixel_depth in pngrutil.c if a user transform needs it. - Changed several division operations to right-shifts in pngvcrd.c - -Version 1.0.4b [September 30, 1999] - Added parentheses in line 3732 of pngvcrd.c - Added a comment in makefile.linux warning about buggy -O3 in pgcc 2.95.1 - -Version 1.0.4c [October 1, 1999] - Added a "png_check_version" function in png.c and pngtest.c that will generate - a helpful compiler error if an old png.h is found in the search path. - Changed type of png_user_transform_depth|channels from int to png_byte. - Added "Libpng is OSI Certified Open Source Software" statement to png.h - -Version 1.0.4d [October 6, 1999] - Changed 0.45 to 0.45455 in png_set_sRGB() - Removed unused PLTE entries from pngnow.png - Re-enabled some parts of pngvcrd.c (png_combine_row) that work properly. - -Version 1.0.4e [October 10, 1999] - Fixed sign error in pngvcrd.c (Greg Roelofs) - Replaced some instances of memcpy with simple assignments in pngvcrd (GR-P) - -Version 1.0.4f [October 15, 1999] - Surrounded example.c code with #if 0 .. #endif to prevent people from - inadvertently trying to compile it. - Changed png_get_header_version() from a function to a macro in png.h - Added type casting mostly in pngrtran.c and pngwtran.c - Removed some pointless "ptr = NULL" in pngmem.c - Added a "contrib" directory containing the source code from Greg's book. - -Version 1.0.5 [October 15, 1999] - Minor editing of the INSTALL and README files. - -Version 1.0.5a [October 23, 1999] - Added contrib/pngsuite and contrib/pngminus (Willem van Schaik) - Fixed a typo in the png_set_sRGB() function call in example.c (Jan Nijtmans) - Further optimization and bugfix of pngvcrd.c - Revised pngset.c so that it does not allocate or free memory in the user's - text_ptr structure. Instead, it makes its own copy. - Created separate write_end_info_struct in pngtest.c for a more severe test. - Added code in pngwrite.c to free info_ptr->text[i].key to stop a memory leak. - -Version 1.0.5b [November 23, 1999] - Moved PNG_FLAG_HAVE_CHUNK_HEADER, PNG_FLAG_BACKGROUND_IS_GRAY and - PNG_FLAG_WROTE_tIME from flags to mode. - Added png_write_info_before_PLTE() function. - Fixed some typecasting in contrib/gregbook/*.c - Updated scripts/makevms.com and added makevms.com to contrib/gregbook - and contrib/pngminus (Martin Zinser) - -Version 1.0.5c [November 26, 1999] - Moved png_get_header_version from png.h to png.c, to accommodate ansi2knr. - Removed all global arrays (according to PNG_NO_GLOBAL_ARRAYS macro), to - accommodate making DLL's: Moved usr_png_ver from global variable to function - png_get_header_ver() in png.c. Moved png_sig to png_sig_bytes in png.c and - eliminated use of png_sig in pngwutil.c. Moved the various png_CHNK arrays - into pngtypes.h. Eliminated use of global png_pass arrays. Declared the - png_CHNK and png_pass arrays to be "const". Made the global arrays - available to applications (although none are used in libpng itself) when - PNG_NO_GLOBAL_ARRAYS is not defined or when PNG_GLOBAL_ARRAYS is defined. - Removed some extraneous "-I" from contrib/pngminus/makefile.std - Changed the PNG_sRGB_INTENT macros in png.h to be consistent with PNG-1.2. - Change PNG_SRGB_INTENT to PNG_sRGB_INTENT in libpng.txt and libpng.3 - -Version 1.0.5d [November 29, 1999] - Add type cast (png_const_charp) two places in png.c - Eliminated pngtypes.h; use macros instead to declare PNG_CHNK arrays. - Renamed "PNG_GLOBAL_ARRAYS" to "PNG_USE_GLOBAL_ARRAYS" and made available - to applications a macro "PNG_USE_LOCAL_ARRAYS". - comment out (with #ifdef) all the new declarations when - PNG_USE_GLOBAL_ARRAYS is defined. - Added PNG_EXPORT_VAR macro to accommodate making DLL's. - -Version 1.0.5e [November 30, 1999] - Added iCCP, iTXt, and sPLT support; added "lang" member to the png_text - structure; refactored the inflate/deflate support to make adding new chunks - with trailing compressed parts easier in the future, and added new functions - png_free_iCCP, png_free_pCAL, png_free_sPLT, png_free_text, png_get_iCCP, - png_get_spalettes, png_set_iCCP, png_set_spalettes (Eric S. Raymond). - NOTE: Applications that write text chunks MUST define png_text->lang - before calling png_set_text(). It must be set to NULL if you want to - write tEXt or zTXt chunks. If you want your application to be able to - run with older versions of libpng, use - - #ifdef PNG_iTXt_SUPPORTED - png_text[i].lang = NULL; - #endif - - Changed png_get_oFFs() and png_set_oFFs() to use signed rather than unsigned - offsets (Eric S. Raymond). - Combined PNG_READ_cHNK_SUPPORTED and PNG_WRITE_cHNK_SUPPORTED macros into - PNG_cHNK_SUPPORTED and combined the three types of PNG_text_SUPPORTED - macros, leaving the separate macros also available. - Removed comments on #endifs at the end of many short, non-nested #if-blocks. - -Version 1.0.5f [December 6, 1999] - Changed makefile.solaris to issue a warning about potential problems when - the ucb "ld" is in the path ahead of the ccs "ld". - Removed "- [date]" from the "synopsis" line in libpng.3 and libpngpf.3. - Added sCAL chunk support (Eric S. Raymond). - -Version 1.0.5g [December 7, 1999] - Fixed "png_free_spallettes" typo in png.h - Added code to handle new chunks in pngpread.c - Moved PNG_CHNK string macro definitions outside of PNG_NO_EXTERN block - Added "translated_key" to png_text structure and png_write_iTXt(). - Added code in pngwrite.c to work around a newly discovered zlib bug. - -Version 1.0.5h [December 10, 1999] - NOTE: regarding the note for version 1.0.5e, the following must also - be included in your code: - png_text[i].translated_key = NULL; - Unknown chunk handling is now supported. - Option to eliminate all floating point support was added. Some new - fixed-point functions such as png_set_gAMA_fixed() were added. - Expanded tabs and removed trailing blanks in source files. - -Version 1.0.5i [December 13, 1999] - Added some type casts to silence compiler warnings. - Renamed "png_free_spalette" to "png_free_spalettes" for consistency. - Removed leading blanks from a #define in pngvcrd.c - Added some parameters to the new png_set_keep_unknown_chunks() function. - Added a test for up->location != 0 in the first instance of writing - unknown chunks in pngwrite.c - Changed "num" to "i" in png_free_spalettes() and png_free_unknowns() to - prevent recursion. - Added png_free_hIST() function. - Various patches to fix bugs in the sCAL and integer cHRM processing, - and to add some convenience macros for use with sCAL. - -Version 1.0.5j [December 21, 1999] - Changed "unit" parameter of png_write_sCAL from png_byte to int, to work - around buggy compilers. - Added new type "png_fixed_point" for integers that hold float*100000 values - Restored backward compatibility of tEXt/zTXt chunk processing: - Restored the first four members of png_text to the same order as v.1.0.5d. - Added members "lang_key" and "itxt_length" to png_text struct. Set - text_length=0 when "text" contains iTXt data. Use the "compression" - member to distinguish among tEXt/zTXt/iTXt types. Added - PNG_ITXT_COMPRESSION_NONE (1) and PNG_ITXT_COMPRESSION_zTXt(2) macros. - The "Note" above, about backward incompatibility of libpng-1.0.5e, no - longer applies. - Fixed png_read|write_iTXt() to read|write parameters in the right order, - and to write the iTXt chunk after IDAT if it appears in the end_ptr. - Added pnggccrd.c, version of pngvcrd.c Intel assembler for gcc (Greg Roelofs) - Reversed the order of trying to write floating-point and fixed-point gAMA. - -Version 1.0.5k [December 27, 1999] - Added many parentheses, e.g., "if (a && b & c)" becomes "if (a && (b & c))" - Added png_handle_as_unknown() function (Glenn) - Added png_free_chunk_list() function and chunk_list and num_chunk_list members - of png_ptr. - Eliminated erroneous warnings about multiple sPLT chunks and sPLT-after-PLTE. - Fixed a libpng-1.0.5h bug in pngrutil.c that was issuing erroneous warnings - about ignoring incorrect gAMA with sRGB (gAMA was in fact not ignored) - Added png_free_tRNS(); png_set_tRNS() now malloc's its own trans array (ESR). - Define png_get_int_32 when oFFs chunk is supported as well as when pCAL is. - Changed type of proflen from png_int_32 to png_uint_32 in png_get_iCCP(). - -Version 1.0.5l [January 1, 2000] - Added functions png_set_read_user_chunk_fn() and png_get_user_chunk_ptr() - for setting a callback function to handle unknown chunks and for - retrieving the associated user pointer (Glenn). - -Version 1.0.5m [January 7, 2000] - Added high-level functions png_read_png(), png_write_png(), png_free_pixels(). - -Version 1.0.5n [January 9, 2000] - Added png_free_PLTE() function, and modified png_set_PLTE() to malloc its - own memory for info_ptr->palette. This makes it safe for the calling - application to free its copy of the palette any time after it calls - png_set_PLTE(). - -Version 1.0.5o [January 20, 2000] - Cosmetic changes only (removed some trailing blanks and TABs) - -Version 1.0.5p [January 31, 2000] - Renamed pngdll.mak to makefile.bd32 - Cosmetic changes in pngtest.c - -Version 1.0.5q [February 5, 2000] - Relocated the makefile.solaris warning about PATH problems. - Fixed pngvcrd.c bug by pushing/popping registers in mmxsupport (Bruce Oberg) - Revised makefile.gcmmx - Added PNG_SETJMP_SUPPORTED, PNG_SETJMP_NOT_SUPPORTED, and PNG_ABORT() macros - -Version 1.0.5r [February 7, 2000] - Removed superfluous prototype for png_get_itxt from png.h - Fixed a bug in pngrtran.c that improperly expanded the background color. - Return *num_text=0 from png_get_text() when appropriate, and fix documentation - of png_get_text() in libpng.txt/libpng.3. - -Version 1.0.5s [February 18, 2000] - Added "png_jmp_env()" macro to pngconf.h, to help people migrate to the - new error handler that's planned for the next libpng release, and changed - example.c, pngtest.c, and contrib programs to use this macro. - Revised some of the DLL-export macros in pngconf.h (Greg Roelofs) - Fixed a bug in png_read_png() that caused it to fail to expand some images - that it should have expanded. - Fixed some mistakes in the unused and undocumented INCH_CONVERSIONS functions - in pngget.c - Changed the allocation of palette, history, and trans arrays back to - the version 1.0.5 method (linking instead of copying) which restores - backward compatibility with version 1.0.5. Added some remarks about - that in example.c. Added "free_me" member to info_ptr and png_ptr - and added png_free_data() function. - Updated makefile.linux and makefile.gccmmx to make directories conditionally. - Made cosmetic changes to pngasmrd.h - Added png_set_rows() and png_get_rows(), for use with png_read|write_png(). - Modified png_read_png() to allocate info_ptr->row_pointers only if it - hasn't already been allocated. - -Version 1.0.5t [March 4, 2000] - Changed png_jmp_env() migration aiding macro to png_jmpbuf(). - Fixed "interlace" typo (should be "interlaced") in contrib/gregbook/read2-x.c - Fixed bug with use of PNG_BEFORE_IHDR bit in png_ptr->mode, introduced when - PNG_FLAG_HAVE_CHUNK_HEADER was moved into png_ptr->mode in version 1.0.5b - Files in contrib/gregbook were revised to use png_jmpbuf() and to select - a 24-bit visual if one is available, and to allow abbreviated options. - Files in contrib/pngminus were revised to use the png_jmpbuf() macro. - Removed spaces in makefile.linux and makefile.gcmmx, introduced in 1.0.5s - -Version 1.0.5u [March 5, 2000] - Simplified the code that detects old png.h in png.c and pngtest.c - Renamed png_spalette (_p, _pp) to png_sPLT_t (_tp, _tpp) - Increased precision of rgb_to_gray calculations from 8 to 15 bits and - added png_set_rgb_to_gray_fixed() function. - Added makefile.bc32 (32-bit Borland C++, C mode) - -Version 1.0.5v [March 11, 2000] - Added some parentheses to the png_jmpbuf macro definition. - Updated references to the zlib home page, which has moved to freesoftware.com. - Corrected bugs in documentation regarding png_read_row() and png_write_row(). - Updated documentation of png_rgb_to_gray calculations in libpng.3/libpng.txt. - Renamed makefile.borland,turboc3 back to makefile.bor,tc3 as in version 1.0.3, - revised borland makefiles; added makefile.ibmvac3 and makefile.gcc (Cosmin) - -Version 1.0.6 [March 20, 2000] - Minor revisions of makefile.bor, libpng.txt, and gregbook/rpng2-win.c - Added makefile.sggcc (SGI IRIX with gcc) - -Version 1.0.6d [April 7, 2000] - Changed sprintf() to strcpy() in png_write_sCAL_s() to work without STDIO - Added data_length parameter to png_decompress_chunk() function - Revised documentation to remove reference to abandoned png_free_chnk functions - Fixed an error in png_rgb_to_gray_fixed() - Revised example.c, usage of png_destroy_write_struct(). - Renamed makefile.ibmvac3 to makefile.ibmc, added libpng.icc IBM project file - Added a check for info_ptr->free_me&PNG_FREE_TEXT when freeing text in png.c - Simplify png_sig_bytes() function to remove use of non-ISO-C strdup(). - -Version 1.0.6e [April 9, 2000] - Added png_data_freer() function. - In the code that checks for over-length tRNS chunks, added check of - info_ptr->num_trans as well as png_ptr->num_trans (Matthias Benckmann) - Minor revisions of libpng.txt/libpng.3. - Check for existing data and free it if the free_me flag is set, in png_set_*() - and png_handle_*(). - Only define PNG_WEIGHTED_FILTERS_SUPPORTED when PNG_FLOATING_POINT_SUPPORTED - is defined. - Changed several instances of PNG_NO_CONSOLE_ID to PNG_NO_STDIO in pngrutil.c - and mentioned the purposes of the two macros in libpng.txt/libpng.3. - -Version 1.0.6f [April 14, 2000] - Revised png_set_iCCP() and png_set_rows() to avoid prematurely freeing data. - Add checks in png_set_text() for NULL members of the input text structure. - Revised libpng.txt/libpng.3. - Removed superfluous prototype for png_set_iTXt from png.h - Removed "else" from pngread.c, after png_error(), and changed "0" to "length". - Changed several png_errors about malformed ancillary chunks to png_warnings. - -Version 1.0.6g [April 24, 2000] - Added png_pass-* arrays to pnggccrd.c when PNG_USE_LOCAL_ARRAYS is defined. - Relocated paragraph about png_set_background() in libpng.3/libpng.txt - and other revisions (Matthias Benckmann) - Relocated info_ptr->free_me, png_ptr->free_me, and other info_ptr and - png_ptr members to restore binary compatibility with libpng-1.0.5 - (breaks compatibility with libpng-1.0.6). - -Version 1.0.6h [April 24, 2000] - Changed shared library so-number pattern from 2.x.y.z to xy.z (this builds - libpng.so.10 & libpng.so.10.6h instead of libpng.so.2 & libpng.so.2.1.0.6h) - This is a temporary change for test purposes. - -Version 1.0.6i [May 2, 2000] - Rearranged some members at the end of png_info and png_struct, to put - unknown_chunks_num and free_me within the original size of the png_structs - and free_me, png_read_user_fn, and png_free_fn within the original png_info, - because some old applications allocate the structs directly instead of - using png_create_*(). - Added documentation of user memory functions in libpng.txt/libpng.3 - Modified png_read_png so that it will use user_allocated row_pointers - if present, unless free_me directs that it be freed, and added description - of the use of png_set_rows() and png_get_rows() in libpng.txt/libpng.3. - Added PNG_LEGACY_SUPPORTED macro, and #ifdef out all new (since version - 1.00) members of png_struct and png_info, to regain binary compatibility - when you define this macro. Capabilities lost in this event - are user transforms (new in version 1.0.0),the user transform pointer - (new in version 1.0.2), rgb_to_gray (new in 1.0.5), iCCP, sCAL, sPLT, - the high-level interface, and unknown chunks support (all new in 1.0.6). - This was necessary because of old applications that allocate the structs - directly as authors were instructed to do in libpng-0.88 and earlier, - instead of using png_create_*(). - Added modes PNG_CREATED_READ_STRUCT and PNG_CREATED_WRITE_STRUCT which - can be used to detect codes that directly allocate the structs, and - code to check these modes in png_read_init() and png_write_init() and - generate a libpng error if the modes aren't set and PNG_LEGACY_SUPPORTED - was not defined. - Added makefile.intel and updated makefile.watcom (Pawel Mrochen) - -Version 1.0.6j [May 3, 2000] - Overloaded png_read_init() and png_write_init() with macros that convert - calls to png_read_init_2() or png_write_init_2() that check the version - and structure sizes. - -Version 1.0.7beta11 [May 7, 2000] - Removed the new PNG_CREATED_READ_STRUCT and PNG_CREATED_WRITE_STRUCT modes - which are no longer used. - Eliminated the three new members of png_text when PNG_LEGACY_SUPPORTED is - defined or when neither PNG_READ_iTXt_SUPPORTED nor PNG_WRITE_iTXt_SUPPORTED - is defined. - Made PNG_NO_READ|WRITE_iTXt the default setting, to avoid memory - overrun when old applications fill the info_ptr->text structure directly. - Added PNGAPI macro, and added it to the definitions of all exported functions. - Relocated version macro definitions ahead of the includes of zlib.h and - pngconf.h in png.h. - -Version 1.0.7beta12 [May 12, 2000] - Revised pngset.c to avoid a problem with expanding the png_debug macro. - Deleted some extraneous defines from pngconf.h - Made PNG_NO_CONSOLE_IO the default condition when PNG_BUILD_DLL is defined. - Use MSC _RPTn debugging instead of fprintf if _MSC_VER is defined. - Added png_access_version_number() function. - Check for mask&PNG_FREE_CHNK (for TEXT, SCAL, PCAL) in png_free_data(). - Expanded libpng.3/libpng.txt information about png_data_freer(). - -Version 1.0.7beta14 [May 17, 2000] (beta13 was not published) - Changed pnggccrd.c and pngvcrd.c to handle bad adaptive filter types as - warnings instead of errors, as pngrutil.c does. - Set the PNG_INFO_IDAT valid flag in png_set_rows() so png_write_png() - will actually write IDATs. - Made the default PNG_USE_LOCAL_ARRAYS depend on PNG_DLL instead of WIN32. - Make png_free_data() ignore its final parameter except when freeing data - that can have multiple instances (text, sPLT, unknowns). - Fixed a new bug in png_set_rows(). - Removed info_ptr->valid tests from png_free_data(), as in version 1.0.5. - Added png_set_invalid() function. - Fixed incorrect illustrations of png_destroy_write_struct() in example.c. - -Version 1.0.7beta15 [May 30, 2000] - Revised the deliberately erroneous Linux setjmp code in pngconf.h to produce - fewer error messages. - Rearranged checks for Z_OK to check the most likely path first in pngpread.c - and pngwutil.c. - Added checks in pngtest.c for png_create_*() returning NULL, and mentioned - in libpng.txt/libpng.3 the need for applications to check this. - Changed names of png_default_*() functions in pngtest to pngtest_*(). - Changed return type of png_get_x|y_offset_*() from png_uint_32 to png_int_32. - Fixed some bugs in the unused PNG_INCH_CONVERSIONS functions in pngget.c - Set each pointer to NULL after freeing it in png_free_data(). - Worked around a problem in pngconf.h; AIX's strings.h defines an "index" - macro that conflicts with libpng's png_color_16.index. (Dimitri - Papadapoulos) - Added "msvc" directory with MSVC++ project files (Simon-Pierre Cadieux). - -Version 1.0.7beta16 [June 4, 2000] - Revised the workaround of AIX string.h "index" bug. - Added a check for overlength PLTE chunk in pngrutil.c. - Added PNG_NO_POINTER_INDEXING macro to use array-indexing instead of pointer - indexing in pngrutil.c and pngwutil.c to accommodate a buggy compiler. - Added a warning in png_decompress_chunk() when it runs out of data, e.g. - when it tries to read an erroneous PhotoShop iCCP chunk. - Added PNG_USE_DLL macro. - Revised the copyright/disclaimer/license notice. - Added contrib/msvctest directory - -Version 1.0.7rc1 [June 9, 2000] - Corrected the definition of PNG_TRANSFORM_INVERT_ALPHA (0x0400 not 0x0200) - Added contrib/visupng directory (Willem van Schaik) - -Version 1.0.7beta18 [June 23, 2000] - Revised PNGAPI definition, and pngvcrd.c to work with __GCC__ - and do not redefine PNGAPI if it is passed in via a compiler directive. - Revised visupng/PngFile.c to remove returns from within the Try block. - Removed leading underscores from "_PNG_H" and "_PNG_SAVE_BSD_SOURCE" macros. - Updated contrib/visupng/cexcept.h to version 1.0.0. - Fixed bugs in pngwrite.c and pngwutil.c that prevented writing iCCP chunks. - -Version 1.0.7rc2 [June 28, 2000] - Updated license to include disclaimers required by UCITA. - Fixed "DJBPP" typo in pnggccrd.c introduced in beta18. - -Version 1.0.7 [July 1, 2000] - Revised the definition of "trans_values" in libpng.3/libpng.txt - -Version 1.0.8beta1 [July 8, 2000] - Added png_free(png_ptr, key) two places in pngpread.c to stop memory leaks. - Changed PNG_NO_STDIO to PNG_NO_CONSOLE_IO, several places in pngrutil.c and - pngwutil.c. - Changed PNG_EXPORT_VAR to use PNG_IMPEXP, in pngconf.h. - Removed unused "#include " from png.c - Added WindowsCE support. - Revised pnggccrd.c to work with gcc-2.95.2 and in the Cygwin environment. - -Version 1.0.8beta2 [July 10, 2000] - Added project files to the wince directory and made further revisions - of pngtest.c, pngrio.c, and pngwio.c in support of WindowsCE. - -Version 1.0.8beta3 [July 11, 2000] - Only set the PNG_FLAG_FREE_TRNS or PNG_FREE_TRNS flag in png_handle_tRNS() - for indexed-color input files to avoid potential double-freeing trans array - under some unusual conditions; problem was introduced in version 1.0.6f. - Further revisions to pngtest.c and files in the wince subdirectory. - -Version 1.0.8beta4 [July 14, 2000] - Added the files pngbar.png and pngbar.jpg to the distribution. - Added makefile.cygwin, and cygwin support in pngconf.h - Added PNG_NO_ZALLOC_ZERO macro (makes png_zalloc skip zeroing memory) - -Version 1.0.8rc1 [July 16, 2000] - Revised png_debug() macros and statements to eliminate compiler warnings. - -Version 1.0.8 [July 24, 2000] - Added png_flush() in pngwrite.c, after png_write_IEND(). - Updated makefile.hpux to build a shared library. - -Version 1.0.9beta1 [November 10, 2000] - Fixed typo in scripts/makefile.hpux - Updated makevms.com in scripts and contrib/* and contrib/* (Martin Zinser) - Fixed seqence-point bug in contrib/pngminus/png2pnm (Martin Zinser) - Changed "cdrom.com" in documentation to "libpng.org" - Revised pnggccrd.c to get it all working, and updated makefile.gcmmx (Greg). - Changed type of "params" from voidp to png_voidp in png_read|write_png(). - Make sure PNGAPI and PNG_IMPEXP are defined in pngconf.h. - Revised the 3 instances of WRITEFILE in pngtest.c. - Relocated "msvc" and "wince" project subdirectories into "dll" subdirectory. - Updated png.rc in dll/msvc project - Revised makefile.dec to define and use LIBPATH and INCPATH - Increased size of global png_libpng_ver[] array from 12 to 18 chars. - Made global png_libpng_ver[], png_sig[] and png_pass_*[] arrays const. - Removed duplicate png_crc_finish() from png_handle_bKGD() function. - Added a warning when application calls png_read_update_info() multiple times. - Revised makefile.cygwin - Fixed bugs in iCCP support in pngrutil.c and pngwutil.c. - Replaced png_set_empty_plte_permitted() with png_permit_mng_features(). - -Version 1.0.9beta2 [November 19, 2000] - Renamed the "dll" subdirectory "projects". - Added borland project files to "projects" subdirectory. - Set VS_FF_PRERELEASE and VS_FF_PATCHED flags in msvc/png.rc when appropriate. - Add error message in png_set_compression_buffer_size() when malloc fails. - -Version 1.0.9beta3 [November 23, 2000] - Revised PNG_LIBPNG_BUILD_TYPE macro in png.h, used in the msvc project. - Removed the png_flush() in pngwrite.c that crashes some applications - that don't set png_output_flush_fn. - Added makefile.macosx and makefile.aix to scripts directory. - -Version 1.0.9beta4 [December 1, 2000] - Change png_chunk_warning to png_warning in png_check_keyword(). - Increased the first part of msg buffer from 16 to 18 in png_chunk_error(). - -Version 1.0.9beta5 [December 15, 2000] - Added support for filter method 64 (for PNG datastreams embedded in MNG). - -Version 1.0.9beta6 [December 18, 2000] - Revised png_set_filter() to accept filter method 64 when appropriate. - Added new PNG_HAVE_PNG_SIGNATURE bit to png_ptr->mode and use it to - help prevent applications from using MNG features in PNG datastreams. - Added png_permit_mng_features() function. - Revised libpng.3/libpng.txt. Changed "filter type" to "filter method". - -Version 1.0.9rc1 [December 23, 2000] - Revised test for PNG_HAVE_PNG_SIGNATURE in pngrutil.c - Fixed error handling of unknown compression type in png_decompress_chunk(). - In pngconf.h, define __cdecl when _MSC_VER is defined. - -Version 1.0.9beta7 [December 28, 2000] - Changed PNG_TEXT_COMPRESSION_zTXt to PNG_COMPRESSION_TYPE_BASE several places. - Revised memory management in png_set_hIST and png_handle_hIST in a backward - compatible manner. PLTE and tRNS were revised similarly. - Revised the iCCP chunk reader to ignore trailing garbage. - -Version 1.0.9beta8 [January 12, 2001] - Moved pngasmrd.h into pngconf.h. - Improved handling of out-of-spec garbage iCCP chunks generated by PhotoShop. - -Version 1.0.9beta9 [January 15, 2001] - Added png_set_invalid, png_permit_mng_features, and png_mmx_supported to - wince and msvc project module definition files. - Minor revision of makefile.cygwin. - Fixed bug with progressive reading of narrow interlaced images in pngpread.c - -Version 1.0.9beta10 [January 16, 2001] - Do not typedef png_FILE_p in pngconf.h when PNG_NO_STDIO is defined. - Fixed "png_mmx_supported" typo in project definition files. - -Version 1.0.9beta11 [January 19, 2001] - Updated makefile.sgi to make shared library. - Removed png_mmx_support() function and disabled PNG_MNG_FEATURES_SUPPORTED - by default, for the benefit of DLL forward compatibility. These will - be re-enabled in version 1.2.0. - -Version 1.0.9rc2 [January 22, 2001] - Revised cygwin support. - -Version 1.0.9 [January 31, 2001] - Added check of cygwin's ALL_STATIC in pngconf.h - Added "-nommx" parameter to contrib/gregbook/rpng2-win and rpng2-x demos. - -Version 1.0.10beta1 [March 14, 2001] - Revised makefile.dec, makefile.sgi, and makefile.sggcc; added makefile.hpgcc. - Reformatted libpng.3 to eliminate bad line breaks. - Added checks for _mmx_supported in the read_filter_row function of pnggccrd.c - Added prototype for png_mmx_support() near the top of pnggccrd.c - Moved some error checking from png_handle_IHDR to png_set_IHDR. - Added PNG_NO_READ_SUPPORTED and PNG_NO_WRITE_SUPPORTED macros. - Revised png_mmx_support() function in pnggccrd.c - Restored version 1.0.8 PNG_WRITE_EMPTY_PLTE_SUPPORTED behavior in pngwutil.c - Fixed memory leak in contrib/visupng/PngFile.c - Fixed bugs in png_combine_row() in pnggccrd.c and pngvcrd.c (C version) - Added warnings when retrieving or setting gamma=0. - Increased the first part of msg buffer from 16 to 18 in png_chunk_warning(). - -Version 1.0.10rc1 [March 23, 2001] - Changed all instances of memcpy, strcpy, and strlen to png_memcpy, png_strcpy, - and png_strlen. - Revised png_mmx_supported() function in pnggccrd.c to return proper value. - Fixed bug in progressive reading (pngpread.c) with small images (height < 8). - -Version 1.0.10 [March 30, 2001] - Deleted extraneous space (introduced in 1.0.9) from line 42 of makefile.cygwin - Added beos project files (Chris Herborth) - -Version 1.0.11beta1 [April 3, 2001] - Added type casts on several png_malloc() calls (Dimitri Papadapoulos). - Removed a no-longer needed AIX work-around from pngconf.h - Changed several "//" single-line comments to C-style in pnggccrd.c - -Version 1.0.11beta2 [April 11, 2001] - Removed PNGAPI from several functions whose prototypes did not have PNGAPI. - Updated scripts/pngos2.def - -Version 1.0.11beta3 [April 14, 2001] - Added checking the results of many instances of png_malloc() for NULL - -Version 1.0.11beta4 [April 20, 2001] - Undid the changes from version 1.0.11beta3. Added a check for NULL return - from user's malloc_fn(). - Removed some useless type casts of the NULL pointer. - Added makefile.netbsd - -Version 1.0.11 [April 27, 2001] - Revised makefile.netbsd - -Version 1.0.12beta1 [May 14, 2001] - Test for Windows platform in pngconf.h when including malloc.h (Emmanuel Blot) - Updated makefile.cygwin and handling of Cygwin's ALL_STATIC in pngconf.h - Added some never-to-be-executed code in pnggccrd.c to quiet compiler warnings. - Eliminated the png_error about apps using png_read|write_init(). Instead, - libpng will reallocate the png_struct and info_struct if they are too small. - This retains future binary compatibility for old applications written for - libpng-0.88 and earlier. - -Version 1.2.0beta1 [May 6, 2001] - Bumped DLLNUM to 2. - Re-enabled PNG_MNG_FEATURES_SUPPORTED and enabled PNG_ASSEMBLER_CODE_SUPPORTED - by default. - Added runtime selection of MMX features. - Added png_set_strip_error_numbers function and related macros. - -Version 1.2.0beta2 [May 7, 2001] - Finished merging 1.2.0beta1 with version 1.0.11 - Added a check for attempts to read or write PLTE in grayscale PNG datastreams. - -Version 1.2.0beta3 [May 17, 2001] - Enabled user memory function by default. - Modified png_create_struct so it passes user mem_ptr to user memory allocator. - Increased png_mng_features flag from png_byte to png_uint_32. - Bumped shared-library (so-number) and dll-number to 3. - -Version 1.2.0beta4 [June 23, 2001] - Check for missing profile length field in iCCP chunk and free chunk_data - in case of truncated iCCP chunk. - Bumped shared-library number to 3 in makefile.sgi and makefile.sggcc - Bumped dll-number from 2 to 3 in makefile.cygwin - Revised contrib/gregbook/rpng*-x.c to avoid a memory leak and to exit cleanly - if user attempts to run it on an 8-bit display. - Updated contrib/gregbook - Use png_malloc instead of png_zalloc to allocate palette in pngset.c - Updated makefile.ibmc - Added some typecasts to eliminate gcc 3.0 warnings. Changed prototypes - of png_write_oFFS width and height from png_uint_32 to png_int_32. - Updated example.c - Revised prototypes for png_debug_malloc and png_debug_free in pngtest.c - -Version 1.2.0beta5 [August 8, 2001] - Revised contrib/gregbook - Revised makefile.gcmmx - Revised pnggccrd.c to conditionally compile some thread-unsafe code only - when PNG_THREAD_UNSAFE_OK is defined. - Added tests to prevent pngwutil.c from writing a bKGD or tRNS chunk with - value exceeding 2^bit_depth-1 - Revised makefile.sgi and makefile.sggcc - Replaced calls to fprintf(stderr,...) with png_warning() in pnggccrd.c - Removed restriction that do_invert_mono only operate on 1-bit opaque files - -Version 1.2.0 [September 1, 2001] - Changed a png_warning() to png_debug() in pnggccrd.c - Fixed contrib/gregbook/rpng-x.c, rpng2-x.c to avoid crash with XFreeGC(). - -Version 1.2.1beta1 [October 19, 2001] - Revised makefile.std in contrib/pngminus - Include background_1 in png_struct regardless of gamma support. - Revised makefile.netbsd and makefile.macosx, added makefile.darwin. - Revised example.c to provide more details about using row_callback(). - -Version 1.2.1beta2 [October 25, 2001] - Added type cast to each NULL appearing in a function call, except for - WINCE functions. - Added makefile.so9. - -Version 1.2.1beta3 [October 27, 2001] - Removed type casts from all NULLs. - Simplified png_create_struct_2(). - -Version 1.2.1beta4 [November 7, 2001] - Revised png_create_info_struct() and png_creat_struct_2(). - Added error message if png_write_info() was omitted. - Type cast NULLs appearing in function calls when _NO_PROTO or - PNG_TYPECAST_NULL is defined. - -Version 1.2.1rc1 [November 24, 2001] - Type cast NULLs appearing in function calls except when PNG_NO_TYPECAST_NULL - is defined. - Changed typecast of "size" argument to png_size_t in pngmem.c calls to - the user malloc_fn, to agree with the prototype in png.h - Added a pop/push operation to pnggccrd.c, to preserve Eflag (Maxim Sobolev) - Updated makefile.sgi to recognize LIBPATH and INCPATH. - Updated various makefiles so "make clean" does not remove previous major - version of the shared library. - -Version 1.2.1rc2 [December 4, 2001] - Always allocate 256-entry internal palette, hist, and trans arrays, to - avoid out-of-bounds memory reference caused by invalid PNG datastreams. - Added a check for prefix_length > data_length in iCCP chunk handler. - -Version 1.2.1 [December 7, 2001] - None. - -Version 1.2.2beta1 [February 22, 2002] - Fixed a bug with reading the length of iCCP profiles (Larry Reeves). - Revised makefile.linux, makefile.gcmmx, and makefile.sgi to generate - libpng.a, libpng12.so (not libpng.so.3), and libpng12/png.h - Revised makefile.darwin to remove "-undefined suppress" option. - Added checks for gamma and chromaticity values over 21474.83, which exceed - the limit for PNG unsigned 32-bit integers when encoded. - Revised calls to png_create_read_struct() and png_create_write_struct() - for simpler debugging. - Revised png_zalloc() so zlib handles errors (uses PNG_FLAG_MALLOC_NULL_MEM_OK) - -Version 1.2.2beta2 [February 23, 2002] - Check chunk_length and idat_size for invalid (over PNG_MAX_UINT) lengths. - Check for invalid image dimensions in png_get_IHDR. - Added missing "fi;" in the install target of the SGI makefiles. - Added install-static to all makefiles that make shared libraries. - Always do gamma compensation when image is partially transparent. - -Version 1.2.2beta3 [March 7, 2002] - Compute background.gray and background_1.gray even when color_type is RGB - in case image gets reduced to gray later. - Modified shared-library makefiles to install pkgconfig/libpngNN.pc. - Export (with PNGAPI) png_zalloc, png_zfree, and png_handle_as_unknown - Removed unused png_write_destroy_info prototype from png.h - Eliminated incorrect use of width_mmx from pnggccrd.c in pixel_bytes == 8 case - Added install-shared target to all makefiles that make shared libraries. - Stopped a double free of palette, hist, and trans when not using free_me. - Added makefile.32sunu for Sun Ultra 32 and makefile.64sunu for Sun Ultra 64. - -Version 1.2.2beta4 [March 8, 2002] - Compute background.gray and background_1.gray even when color_type is RGB - in case image gets reduced to gray later (Jason Summers). - Relocated a misplaced /bin/rm in the "install-shared" makefile targets - Added PNG_1_0_X macro which can be used to build a 1.0.x-compatible library. - -Version 1.2.2beta5 [March 26, 2002] - Added missing PNGAPI to several function definitions. - Check for invalid bit_depth or color_type in png_get_IHDR(), and - check for missing PLTE or IHDR in png_push_read_chunk() (Matthias Clasen). - Revised iTXt support to accept NULL for lang and lang_key. - Compute gamma for color components of background even when color_type is gray. - Changed "()" to "{}" in scripts/libpng.pc.in. - Revised makefiles to put png.h and pngconf.h only in $prefix/include/libpngNN - Revised makefiles to make symlink to libpng.so.NN in addition to libpngNN.so - -Version 1.2.2beta6 [March 31, 2002] - -Version 1.0.13beta1 [March 31, 2002] - Prevent png_zalloc() from trying to memset memory that it failed to acquire. - Add typecasts of PNG_MAX_UINT in pngset_cHRM_fixed() (Matt Holgate). - Ensure that the right function (user or default) is used to free the - png_struct after an error in png_create_read_struct_2(). - -Version 1.2.2rc1 [April 7, 2002] - -Version 1.0.13rc1 [April 7, 2002] - Save the ebx register in pnggccrd.c (Sami Farin) - Add "mem_ptr = png_ptr->mem_ptr" in png_destroy_write_struct() (Paul Gardner). - Updated makefiles to put headers in include/libpng and remove old include/*.h. - -Version 1.2.2 [April 15, 2002] - -Version 1.0.13 [April 15, 2002] - Revised description of png_set_filter() in libpng.3/libpng.txt. - Revised makefile.netbsd and added makefile.neNNbsd and makefile.freebsd - -Version 1.0.13patch01 [April 17, 2002] - -Version 1.2.2patch01 [April 17, 2002] - Changed ${PNGMAJ}.${PNGVER} bug to ${PNGVER} in makefile.sgi and - makefile.sggcc - Fixed VER -> PNGVER typo in makefile.macosx and added install-static to - install - Added install: target to makefile.32sunu and makefile.64sunu - -Version 1.0.13patch03 [April 18, 2002] - -Version 1.2.2patch03 [April 18, 2002] - Revised 15 makefiles to link libpng.a to libpngNN.a and the include libpng - subdirectory to libpngNN subdirectory without the full pathname. - Moved generation of libpng.pc from "install" to "all" in 15 makefiles. - -Version 1.2.3rc1 [April 28, 2002] - Added install-man target to 15 makefiles (Dimitri Papadopolous-Orfanos). - Added $(DESTDIR) feature to 24 makefiles (Tim Mooney) - Fixed bug with $prefix, should be $(prefix) in makefile.hpux. - Updated cygwin-specific portion of pngconf.h and revised makefile.cygwin - Added a link from libpngNN.pc to libpng.pc in 15 makefiles. - Added links from include/libpngNN/*.h to include/*.h in 24 makefiles. - Revised makefile.darwin to make relative links without full pathname. - Added setjmp() at the end of png_create_*_struct_2() in case user forgets - to put one in their application. - Restored png_zalloc() and png_zfree() prototypes to version 1.2.1 and - removed them from module definition files. - -Version 1.2.3rc2 [May 1, 2002] - Fixed bug in reporting number of channels in pngget.c and pngset.c, - that was introduced in version 1.2.2beta5. - Exported png_zalloc(), png_zfree(), png_default_read(), png_default_write(), - png_default_flush(), and png_push_fill_buffer() and included them in - module definition files. - Added "libpng.pc" dependency to the "install-shared" target in 15 makefiles. - -Version 1.2.3rc3 [May 1, 2002] - Revised prototype for png_default_flush() - Remove old libpng.pc and libpngNN.pc before installing new ones. - -Version 1.2.3rc4 [May 2, 2002] - Typos in *.def files (png_default_read|write -> png_default_read|write_data) - In makefiles, changed rm libpng.NN.pc to rm libpngNN.pc - Added libpng-config and libpngNN-config and modified makefiles to install - them. - Changed $(MANPATH) to $(DESTDIR)$(MANPATH) in makefiles - Added "Win32 DLL VB" configuration to projects/msvc/libpng.dsp - -Version 1.2.3rc5 [May 11, 2002] - Changed "error" and "message" in prototypes to "error_message" and - "warning_message" to avoid namespace conflict. - Revised 15 makefiles to build libpng-config from libpng-config-*.in - Once more restored png_zalloc and png_zfree to regular nonexported form. - Restored png_default_read|write_data, png_default_flush, png_read_fill_buffer - to nonexported form, but with PNGAPI, and removed them from module def - files. - -Version 1.2.3rc6 [May 14, 2002] - Removed "PNGAPI" from png_zalloc() and png_zfree() in png.c - Changed "Gz" to "Gd" in projects/msvc/libpng.dsp and zlib.dsp. - Removed leftover libpng-config "sed" script from four makefiles. - Revised libpng-config creating script in 16 makefiles. - -Version 1.2.3 [May 22, 2002] - Revised libpng-config target in makefile.cygwin. - Removed description of png_set_mem_fn() from documentation. - Revised makefile.freebsd. - Minor cosmetic changes to 15 makefiles, e.g., $(DI) = $(DESTDIR)/$(INCDIR). - Revised projects/msvc/README.txt - Changed -lpng to -lpngNN in LDFLAGS in several makefiles. - -Version 1.2.4beta1 [May 24, 2002] - Added libpng.pc and libpng-config to "all:" target in 16 makefiles. - Fixed bug in 16 makefiles: $(DESTDIR)/$(LIBPATH) to $(DESTDIR)$(LIBPATH) - Added missing "\" before closing double quote in makefile.gcmmx. - Plugged various memory leaks; added png_malloc_warn() and png_set_text_2() - functions. - -Version 1.2.4beta2 [June 25, 2002] - Plugged memory leak of png_ptr->current_text (Matt Holgate). - Check for buffer overflow before reading CRC in pngpread.c (Warwick Allison) - Added -soname to the loader flags in makefile.dec, makefile.sgi, and - makefile.sggcc. - Added "test-installed" target to makefile.linux, makefile.gcmmx, - makefile.sgi, and makefile.sggcc. - -Version 1.2.4beta3 [June 28, 2002] - Plugged memory leak of row_buf in pngtest.c when there is a png_error(). - Detect buffer overflow in pngpread.c when IDAT is corrupted with extra data. - Added "test-installed" target to makefile.32sunu, makefile.64sunu, - makefile.beos, makefile.darwin, makefile.dec, makefile.macosx, - makefile.solaris, makefile.hpux, makefile.hpgcc, and makefile.so9. - -Version 1.2.4rc1 and 1.0.14rc1 [July 2, 2002] - Added "test-installed" target to makefile.cygwin and makefile.sco. - Revised pnggccrd.c to be able to back out version 1.0.x via PNG_1_0_X macro. - -Version 1.2.4 and 1.0.14 [July 8, 2002] - Changed png_warning() to png_error() when width is too large to process. - -Version 1.2.4patch01 [July 20, 2002] - Revised makefile.cygwin to use DLL number 12 instead of 13. - -Version 1.2.5beta1 [August 6, 2002] - Added code to contrib/gregbook/readpng2.c to ignore unused chunks. - Replaced toucan.png in contrib/gregbook (it has been corrupt since 1.0.11) - Removed some stray *.o files from contrib/gregbook. - Changed png_error() to png_warning() about "Too much data" in pngpread.c - and about "Extra compressed data" in pngrutil.c. - Prevent png_ptr->pass from exceeding 7 in png_push_finish_row(). - Updated makefile.hpgcc - Updated png.c and pnggccrd.c handling of return from png_mmx_support() - -Version 1.2.5beta2 [August 15, 2002] - Only issue png_warning() about "Too much data" in pngpread.c when avail_in - is nonzero. - Updated makefiles to install a separate libpng.so.3 with its own rpath. - -Version 1.2.5rc1 and 1.0.15rc1 [August 24, 2002] - Revised makefiles to not remove previous minor versions of shared libraries. - -Version 1.2.5rc2 and 1.0.15rc2 [September 16, 2002] - Revised 13 makefiles to remove "-lz" and "-L$(ZLIBLIB)", etc., from shared - library loader directive. - Added missing "$OBJSDLL" line to makefile.gcmmx. - Added missing "; fi" to makefile.32sunu. - -Version 1.2.5rc3 and 1.0.15rc3 [September 18, 2002] - Revised libpng-config script. - -Version 1.2.5 and 1.0.15 [October 3, 2002] - Revised makefile.macosx, makefile.darwin, makefile.hpgcc, and makefile.hpux, - and makefile.aix. - Relocated two misplaced PNGAPI lines in pngtest.c - -Version 1.2.6beta1 [October 22, 2002] - Commented out warning about uninitialized mmx_support in pnggccrd.c. - Changed "IBMCPP__" flag to "__IBMCPP__" in pngconf.h. - Relocated two more misplaced PNGAPI lines in pngtest.c - Fixed memory overrun bug in png_do_read_filler() with 16-bit datastreams, - introduced in version 1.0.2. - Revised makefile.macosx, makefile.dec, makefile.aix, and makefile.32sunu. - -Version 1.2.6beta2 [November 1, 2002] - Added libpng-config "--ldopts" output. - Added "AR=ar" and "ARFLAGS=rc" and changed "ar rc" to "$(AR) $(ARFLAGS)" - in makefiles. - -Version 1.2.6beta3 [July 18, 2004] - Reverted makefile changes from version 1.2.6beta2 and some of the changes - from version 1.2.6beta1; these will be postponed until version 1.2.7. - Version 1.2.6 is going to be a simple bugfix release. - Changed the one instance of "ln -sf" to "ln -f -s" in each Sun makefile. - Fixed potential overrun in pngerror.c by using strncpy instead of memcpy. - Added "#!/bin/sh" at the top of configure, for recognition of the - 'x' flag under Cygwin (Cosmin). - Optimized vacuous tests that silence compiler warnings, in png.c (Cosmin). - Added support for PNG_USER_CONFIG, in pngconf.h (Cosmin). - Fixed the special memory handler for Borland C under DOS, in pngmem.c - (Cosmin). - Removed some spurious assignments in pngrutil.c (Cosmin). - Replaced 65536 with 65536L, and 0xffff with 0xffffL, to silence warnings - on 16-bit platforms (Cosmin). - Enclosed shift op expressions in parentheses, to silence warnings (Cosmin). - Used proper type png_fixed_point, to avoid problems on 16-bit platforms, - in png_handle_sRGB() (Cosmin). - Added compression_type to png_struct, and optimized the window size - inside the deflate stream (Cosmin). - Fixed definition of isnonalpha(), in pngerror.c and pngrutil.c (Cosmin). - Fixed handling of unknown chunks that come after IDAT (Cosmin). - Allowed png_error() and png_warning() to work even if png_ptr == NULL - (Cosmin). - Replaced row_info->rowbytes with row_bytes in png_write_find_filter() - (Cosmin). - Fixed definition of PNG_LIBPNG_VER_DLLNUM (Simon-Pierre). - Used PNG_LIBPNG_VER and PNG_LIBPNG_VER_STRING instead of the hardcoded - values in png.c (Simon-Pierre, Cosmin). - Initialized png_libpng_ver[] with PNG_LIBPNG_VER_STRING (Simon-Pierre). - Replaced PNG_LIBPNG_VER_MAJOR with PNG_LIBPNG_VER_DLLNUM in png.rc - (Simon-Pierre). - Moved the definition of PNG_HEADER_VERSION_STRING near the definitions - of the other PNG_LIBPNG_VER_... symbols in png.h (Cosmin). - Relocated #ifndef PNGAPI guards in pngconf.h (Simon-Pierre, Cosmin). - Updated scripts/makefile.vc(a)win32 (Cosmin). - Updated the MSVC project (Simon-Pierre, Cosmin). - Updated the Borland C++ Builder project (Cosmin). - Avoided access to asm_flags in pngvcrd.c, if PNG_1_0_X is defined (Cosmin). - Commented out warning about uninitialized mmx_support in pngvcrd.c (Cosmin). - Removed scripts/makefile.bd32 and scripts/pngdef.pas (Cosmin). - Added extra guard around inclusion of Turbo C memory headers, in pngconf.h - (Cosmin). - Renamed projects/msvc/ to projects/visualc6/, and projects/borland/ to - projects/cbuilder5/ (Cosmin). - Moved projects/visualc6/png32ms.def to scripts/pngw32.def, - and projects/visualc6/png.rc to scripts/pngw32.rc (Cosmin). - Added projects/visualc6/pngtest.dsp; removed contrib/msvctest/ (Cosmin). - Changed line endings to DOS style in cbuilder5 and visualc6 files, even - in the tar.* distributions (Cosmin). - Updated contrib/visupng/VisualPng.dsp (Cosmin). - Updated contrib/visupng/cexcept.h to version 2.0.0 (Cosmin). - Added a separate distribution with "configure" and supporting files (Junichi). - -Version 1.2.6beta4 [July 28, 2004] - Added user ability to change png_size_t via a PNG_SIZE_T macro. - Added png_sizeof() and png_convert_size() functions. - Added PNG_SIZE_MAX (maximum value of a png_size_t variable. - Added check in png_malloc_default() for (size_t)size != (png_uint_32)size - which would indicate an overflow. - Changed sPLT failure action from png_error to png_warning and abandon chunk. - Changed sCAL and iCCP failures from png_error to png_warning and abandon. - Added png_get_uint_31(png_ptr, buf) function. - Added PNG_UINT_32_MAX macro. - Renamed PNG_MAX_UINT to PNG_UINT_31_MAX. - Made png_zalloc() issue a png_warning and return NULL on potential - overflow. - Turn on PNG_NO_ZALLOC_ZERO by default in version 1.2.x - Revised "clobber list" in pnggccrd.c so it will compile under gcc-3.4. - Revised Borland portion of png_malloc() to return NULL or issue - png_error() according to setting of PNG_FLAG_MALLOC_NULL_MEM_OK. - Added PNG_NO_SEQUENTIAL_READ_SUPPORTED macro to conditionally remove - sequential read support. - Added some "#if PNG_WRITE_SUPPORTED" blocks. - Added #ifdef to remove some redundancy in png_malloc_default(). - Use png_malloc instead of png_zalloc to allocate the pallete. - -Version 1.0.16rc1 and 1.2.6rc1 [August 4, 2004] - Fixed buffer overflow vulnerability (CVE-2004-0597) in png_handle_tRNS(). - Fixed NULL dereference vulnerability (CVE-2004-0598) in png_handle_iCCP(). - Fixed integer overflow vulnerability (CVE-2004-0599) in png_read_png(). - Fixed some harmless bugs in png_handle_sBIT, etc, that would cause - duplicate chunk types to go undetected. - Fixed some timestamps in the -config version - Rearranged order of processing of color types in png_handle_tRNS(). - Added ROWBYTES macro to calculate rowbytes without integer overflow. - Updated makefile.darwin and removed makefile.macosx from scripts directory. - Imposed default one million column, one-million row limits on the image - dimensions, and added png_set_user_limits() function to override them. - Revised use of PNG_SET_USER_LIMITS_SUPPORTED macro. - Fixed wrong cast of returns from png_get_user_width|height_max(). - Changed some "keep the compiler happy" from empty statements to returns, - Revised libpng.txt to remove 1.2.x stuff from the 1.0.x distribution - -Version 1.0.16rc2 and 1.2.6rc2 [August 7, 2004] - Revised makefile.darwin and makefile.solaris. Removed makefile.macosx. - Revised pngtest's png_debug_malloc() to use png_malloc() instead of - png_malloc_default() which is not supposed to be exported. - Fixed off-by-one error in one of the conversions to PNG_ROWBYTES() in - pngpread.c. Bug was introduced in 1.2.6rc1. - Fixed bug in RGB to RGBX transformation introduced in 1.2.6rc1. - Fixed old bug in RGB to Gray transformation. - Fixed problem with 64-bit compilers by casting arguments to abs() - to png_int_32. - Changed "ln -sf" to "ln -f -s" in three makefiles (solaris, sco, so9). - Changed "HANDLE_CHUNK_*" to "PNG_HANDLE_CHUNK_*" (Cosmin) - Added "-@/bin/rm -f $(DL)/$(LIBNAME).so.$(PNGMAJ)" to 15 *NIX makefiles. - Added code to update the row_info->colortype in png_do_read_filler() (MSB). - -Version 1.0.16rc3 and 1.2.6rc3 [August 9, 2004] - Eliminated use of "abs()" in testing cHRM and gAMA values, to avoid - trouble with some 64-bit compilers. Created PNG_OUT_OF_RANGE() macro. - Revised documentation of png_set_keep_unknown_chunks(). - Check handle_as_unknown status in pngpread.c, as in pngread.c previously. - Moved "PNG_HANDLE_CHUNK_*" macros out of PNG_INTERNAL section of png.h - Added "rim" definitions for CONST4 and CONST6 in pnggccrd.c - -Version 1.0.16rc4 and 1.2.6rc4 [August 10, 2004] - Fixed mistake in pngtest.c introduced in 1.2.6rc2 (declaration of - "pinfo" was out of place). - -Version 1.0.16rc5 and 1.2.6rc5 [August 10, 2004] - Moved "PNG_HANDLE_CHUNK_*" macros out of PNG_ASSEMBLER_CODE_SUPPORTED - section of png.h where they were inadvertently placed in version rc3. - -Version 1.2.6 and 1.0.16 [August 15, 2004] - Revised pngtest so memory allocation testing is only done when PNG_DEBUG==1. - -Version 1.2.7beta1 [August 26, 2004] - Removed unused pngasmrd.h file. - Removed references to uu.net for archived files. Added references to - PNG Spec (second edition) and the PNG ISO/IEC Standard. - Added "test-dd" target in 15 makefiles, to run pngtest in DESTDIR. - Fixed bug with "optimized window size" in the IDAT datastream, that - causes libpng to write PNG files with incorrect zlib header bytes. - -Version 1.2.7beta2 [August 28, 2004] - Fixed bug with sCAL chunk and big-endian machines (David Munro). - Undid new code added in 1.2.6rc2 to update the color_type in - png_set_filler(). - Added png_set_add_alpha() that updates color type. - -Version 1.0.17rc1 and 1.2.7rc1 [September 4, 2004] - Revised png_set_strip_filler() to not remove alpha if color_type has alpha. - -Version 1.2.7 and 1.0.17 [September 12, 2004] - Added makefile.hp64 - Changed projects/msvc/png32ms.def to scripts/png32ms.def in makefile.cygwin - -Version 1.2.8beta1 [November 1, 2004] - Fixed bug in png_text_compress() that would fail to complete a large block. - Fixed bug, introduced in libpng-1.2.7, that overruns a buffer during - strip alpha operation in png_do_strip_filler(). - Added PNG_1_2_X definition in pngconf.h - Use #ifdef to comment out png_info_init in png.c and png_read_init in - pngread.c (as of 1.3.0) - -Version 1.2.8beta2 [November 2, 2004] - Reduce color_type to a nonalpha type after strip alpha operation in - png_do_strip_filler(). - -Version 1.2.8beta3 [November 3, 2004] - Revised definitions of PNG_MAX_UINT_32, PNG_MAX_SIZE, and PNG_MAXSUM - -Version 1.2.8beta4 [November 12, 2004] - Fixed (again) definition of PNG_LIBPNG_VER_DLLNUM in png.h (Cosmin). - Added PNG_LIBPNG_BUILD_PRIVATE in png.h (Cosmin). - Set png_ptr->zstream.data_type to Z_BINARY, to avoid unnecessary detection - of data type in deflate (Cosmin). - Deprecated but continue to support SPECIALBUILD and PRIVATEBUILD in favor of - PNG_LIBPNG_BUILD_SPECIAL_STRING and PNG_LIBPNG_BUILD_PRIVATE_STRING. - -Version 1.2.8beta5 [November 20, 2004] - Use png_ptr->flags instead of png_ptr->transformations to pass - PNG_STRIP_ALPHA info to png_do_strip_filler(), to preserve ABI - compatibility. - Revised handling of SPECIALBUILD, PRIVATEBUILD, - PNG_LIBPNG_BUILD_SPECIAL_STRING and PNG_LIBPNG_BUILD_PRIVATE_STRING. - -Version 1.2.8rc1 [November 24, 2004] - Moved handling of BUILD macros from pngconf.h to png.h - Added definition of PNG_LIBPNG_BASE_TYPE in png.h, inadvertently - omitted from beta5. - Revised scripts/pngw32.rc - Despammed mailing addresses by masking "@" with "at". - Inadvertently installed a supposedly faster test version of pngrutil.c - -Version 1.2.8rc2 [November 26, 2004] - Added two missing "\" in png.h - Change tests in pngread.c and pngpread.c to - if (png_ptr->transformations || (png_ptr->flags&PNG_FLAG_STRIP_ALPHA)) - png_do_read_transformations(png_ptr); - -Version 1.2.8rc3 [November 28, 2004] - Reverted pngrutil.c to version libpng-1.2.8beta5. - Added scripts/makefile.elf with supporting code in pngconf.h for symbol - versioning (John Bowler). - -Version 1.2.8rc4 [November 29, 2004] - Added projects/visualc7 (Simon-pierre). - -Version 1.2.8rc5 [November 29, 2004] - Fixed new typo in scripts/pngw32.rc - -Version 1.2.8 [December 3, 2004] - Removed projects/visualc7, added projects/visualc71. - -Version 1.2.9beta1 [February 21, 2006] - Initialized some structure members in pngwutil.c to avoid gcc-4.0.0 complaints - Revised man page and libpng.txt to make it clear that one should not call - png_read_end or png_write_end after png_read_png or png_write_png. - Updated references to png-mng-implement mailing list. - Fixed an incorrect typecast in pngrutil.c - Added PNG_NO_READ_SUPPORTED conditional for making a write-only library. - Added PNG_NO_WRITE_INTERLACING_SUPPORTED conditional. - Optimized alpha-inversion loops in pngwtran.c - Moved test for nonzero gamma outside of png_build_gamma_table() in pngrtran.c - Make sure num_trans is <= 256 before copying data in png_set_tRNS(). - Make sure num_palette is <= 256 before copying data in png_set_PLTE(). - Interchanged order of write_swap_alpha and write_invert_alpha transforms. - Added parentheses in the definition of PNG_LIBPNG_BUILD_TYPE (Cosmin). - Optimized zlib window flag (CINFO) in contrib/pngsuite/*.png (Cosmin). - Updated scripts/makefile.bc32 for Borland C++ 5.6 (Cosmin). - Exported png_get_uint_32, png_save_uint_32, png_get_uint_16, png_save_uint_16, - png_get_int_32, png_save_int_32, png_get_uint_31 (Cosmin). - Added type cast (png_byte) in png_write_sCAL() (Cosmin). - Fixed scripts/makefile.cygwin (Christian Biesinger, Cosmin). - Default iTXt support was inadvertently enabled. - -Version 1.2.9beta2 [February 21, 2006] - Check for png_rgb_to_gray and png_gray_to_rgb read transformations before - checking for png_read_dither in pngrtran.c - Revised checking of chromaticity limits to accommodate extended RGB - colorspace (John Denker). - Changed line endings in some of the project files to CRLF, even in the - "Unix" tar distributions (Cosmin). - Made png_get_int_32 and png_save_int_32 always available (Cosmin). - Updated scripts/pngos2.def, scripts/pngw32.def and projects/wince/png32ce.def - with the newly exported functions. - Eliminated distributions without the "configure" script. - Updated INSTALL instructions. - -Version 1.2.9beta3 [February 24, 2006] - Fixed CRCRLF line endings in contrib/visupng/VisualPng.dsp - Made libpng.pc respect EXEC_PREFIX (D. P. Kreil, J. Bowler) - Removed reference to pngasmrd.h from Makefile.am - Renamed CHANGES to ChangeLog. - Renamed LICENSE to COPYING. - Renamed ANNOUNCE to NEWS. - Created AUTHORS file. - -Version 1.2.9beta4 [March 3, 2006] - Changed definition of PKGCONFIG from $prefix/lib to $libdir in configure.ac - Reverted to filenames LICENSE and ANNOUNCE; removed AUTHORS and COPYING. - Removed newline from the end of some error and warning messages. - Removed test for sqrt() from configure.ac and configure. - Made swap tables in pngtrans.c PNG_CONST (Carlo Bramix). - Disabled default iTXt support that was inadvertently enabled in - libpng-1.2.9beta1. - Added "OS2" to list of systems that don't need underscores, in pnggccrd.c - Removed libpng version and date from *.c files. - -Version 1.2.9beta5 [March 4, 2006] - Removed trailing blanks from source files. - Put version and date of latest change in each source file, and changed - copyright year accordingly. - More cleanup of configure.ac, Makefile.am, and associated scripts. - Restored scripts/makefile.elf which was inadvertently deleted. - -Version 1.2.9beta6 [March 6, 2006] - Fixed typo (RELEASE) in configuration files. - -Version 1.2.9beta7 [March 7, 2006] - Removed libpng.vers and libpng.sym from libpng12_la_SOURCES in Makefile.am - Fixed inconsistent #ifdef's around png_sig_bytes() and png_set_sCAL_s() - in png.h. - Updated makefile.elf as suggested by debian. - Made cosmetic changes to some makefiles, adding LN_SF and other macros. - Made some makefiles accept "exec_prefix". - -Version 1.2.9beta8 [March 9, 2006] - Fixed some "#if defined (..." which should be "#if defined(..." - Bug introduced in libpng-1.2.8. - Fixed inconsistency in definition of png_default_read_data() - Restored blank that was lost from makefile.sggcc "clean" target in beta7. - Revised calculation of "current" and "major" for irix in ltmain.sh - Changed "mkdir" to "MKDIR_P" in some makefiles. - Separated PNG_EXPAND and PNG_EXPAND_tRNS. - Added png_set_expand_gray_1_2_4_to_8() and deprecated - png_set_gray_1_2_4_to_8() which also expands tRNS to alpha. - -Version 1.2.9beta9 [March 10, 2006] - Include "config.h" in pngconf.h when available. - Added some checks for NULL png_ptr or NULL info_ptr (timeless) - -Version 1.2.9beta10 [March 20, 2006] - Removed extra CR from contrib/visualpng/VisualPng.dsw (Cosmin) - Made pnggccrd.c PIC-compliant (Christian Aichinger). - Added makefile.mingw (Wolfgang Glas). - Revised pngconf.h MMX checking. - -Version 1.2.9beta11 [March 22, 2006] - Fixed out-of-order declaration in pngwrite.c that was introduced in beta9 - Simplified some makefiles by using LIBSO, LIBSOMAJ, and LIBSOVER macros. - -Version 1.2.9rc1 [March 31, 2006] - Defined PNG_USER_PRIVATEBUILD when including "pngusr.h" (Cosmin). - Removed nonsensical assertion check from pngtest.c (Cosmin). - -Version 1.2.9 [April 14, 2006] - Revised makefile.beos and added "none" selector in ltmain.sh - -Version 1.2.10beta1 [April 15, 2006] - Renamed "config.h" to "png_conf.h" and revised Makefile.am to add - -DPNG_BUILDING_LIBPNG to compile directive, and modified pngconf.h - to include png_conf.h only when PNG_BUILDING_LIBPNG is defined. - -Version 1.2.10beta2 [April 15, 2006] - Manually updated Makefile.in and configure. Changed png_conf.h.in - back to config.h. - -Version 1.2.10beta3 [April 15, 2006] - Change png_conf.h back to config.h in pngconf.h. - -Version 1.2.10beta4 [April 16, 2006] - Change PNG_BUILDING_LIBPNG to PNG_CONFIGURE_LIBPNG in config/Makefile*. - -Version 1.2.10beta5 [April 16, 2006] - Added a configure check for compiling assembler code in pnggccrd.c - -Version 1.2.10beta6 [April 17, 2006] - Revised the configure check for pnggccrd.c - Moved -DPNG_CONFIGURE_LIBPNG into @LIBPNG_DEFINES@ - Added @LIBPNG_DEFINES@ to arguments when building libpng.sym - -Version 1.2.10beta7 [April 18, 2006] - Change "exec_prefix=$prefix" to "exec_prefix=$(prefix)" in makefiles. - -Version 1.2.10rc1 [April 19, 2006] - Ensure pngconf.h doesn't define both PNG_USE_PNGGCCRD and PNG_USE_PNGVCRD - Fixed "LN_FS" typo in makefile.sco and makefile.solaris. - -Version 1.2.10rc2 [April 20, 2006] - Added a backslash between -DPNG_CONFIGURE_LIBPNG and -DPNG_NO_ASSEMBLER_CODE - in configure.ac and configure - Made the configure warning about versioned symbols less arrogant. - -Version 1.2.10rc3 [April 21, 2006] - Added a note in libpng.txt that png_set_sig_bytes(8) can be used when - writing an embedded PNG without the 8-byte signature. - Revised makefiles and configure to avoid making links to libpng.so.* - -Version 1.2.10 [April 23, 2006] - Reverted configure to "rc2" state. - -Version 1.2.11beta1 [May 31, 2006] - scripts/libpng.pc.in contained "configure" style version info and would - not work with makefiles. - The shared-library makefiles were linking to libpng.so.0 instead of - libpng.so.3 compatibility as the library. - -Version 1.2.11beta2 [June 2, 2006] - Increased sprintf buffer from 50 to 52 chars in pngrutil.c to avoid - buffer overflow. - Fixed bug in example.c (png_set_palette_rgb -> png_set_palette_to_rgb) - -Version 1.2.11beta3 [June 5, 2006] - Prepended "#! /bin/sh" to ltmail.sh and contrib/pngminus/*.sh (Cosmin). - Removed the accidental leftover Makefile.in~ (Cosmin). - Avoided potential buffer overflow and optimized buffer in - png_write_sCAL(), png_write_sCAL_s() (Cosmin). - Removed the include directories and libraries from CFLAGS and LDFLAGS - in scripts/makefile.gcc (Nelson A. de Oliveira, Cosmin). - -Version 1.2.11beta4 [June 6, 2006] - Allow zero-length IDAT chunks after the entire zlib datastream, but not - after another intervening chunk type. - -Version 1.0.19rc1, 1.2.11rc1 [June 13, 2006] - Deleted extraneous square brackets from [config.h] in configure.ac - -Version 1.0.19rc2, 1.2.11rc2 [June 14, 2006] - Added prototypes for PNG_INCH_CONVERSIONS functions to png.h - Revised INSTALL and autogen.sh - Fixed typo in several makefiles (-W1 should be -Wl) - Added typedef for png_int_32 and png_uint_32 on 64-bit systems. - -Version 1.0.19rc3, 1.2.11rc3 [June 15, 2006] - Removed the new typedefs for 64-bit systems (delay until version 1.4.0) - Added one zero element to png_gamma_shift[] array in pngrtran.c to avoid - reading out of bounds. - -Version 1.0.19rc4, 1.2.11rc4 [June 15, 2006] - Really removed the new typedefs for 64-bit systems. - -Version 1.0.19rc5, 1.2.11rc5 [June 22, 2006] - Removed png_sig_bytes entry from scripts/pngw32.def - -Version 1.0.19, 1.2.11 [June 26, 2006] - None. - -Version 1.0.20, 1.2.12 [June 27, 2006] - Really increased sprintf buffer from 50 to 52 chars in pngrutil.c to avoid - buffer overflow. - -Version 1.2.13beta1 [October 2, 2006] - Removed AC_FUNC_MALLOC from configure.ac - Work around Intel-Mac compiler bug by setting PNG_NO_MMX_CODE in pngconf.h - Change "logical" to "bitwise" throughout documentation. - Detect and fix attempt to write wrong iCCP profile length (CVE-2006-7244) - -Version 1.0.21, 1.2.13 [November 14, 2006] - Fix potential buffer overflow in sPLT chunk handler. - Fix Makefile.am to not try to link to noexistent files. - Check all exported functions for NULL png_ptr. - -Version 1.2.14beta1 [November 17, 2006] - Relocated three misplaced tests for NULL png_ptr. - Built Makefile.in with automake-1.9.6 instead of 1.9.2. - Build configure with autoconf-2.60 instead of 2.59 - -Version 1.2.14beta2 [November 17, 2006] - Added some typecasts in png_zalloc(). - -Version 1.2.14rc1 [November 20, 2006] - Changed "strtod" to "png_strtod" in pngrutil.c - -Version 1.0.22, 1.2.14 [November 27, 2006] - Added missing "$(srcdir)" in Makefile.am and Makefile.in - -Version 1.2.15beta1 [December 3, 2006] - Generated configure with autoconf-2.61 instead of 2.60 - Revised configure.ac to update libpng.pc and libpng-config. - -Version 1.2.15beta2 [December 3, 2006] - Always export MMX asm functions, just stubs if not building pnggccrd.c - -Version 1.2.15beta3 [December 4, 2006] - Add "png_bytep" typecast to profile while calculating length in pngwutil.c - -Version 1.2.15beta4 [December 7, 2006] - Added scripts/CMakeLists.txt - Changed PNG_NO_ASSEMBLER_CODE to PNG_NO_MMX_CODE in scripts, like 1.4.0beta - -Version 1.2.15beta5 [December 7, 2006] - Changed some instances of PNG_ASSEMBLER_* to PNG_MMX_* in pnggccrd.c - Revised scripts/CMakeLists.txt - -Version 1.2.15beta6 [December 13, 2006] - Revised scripts/CMakeLists.txt and configure.ac - -Version 1.2.15rc1 [December 18, 2006] - Revised scripts/CMakeLists.txt - -Version 1.2.15rc2 [December 21, 2006] - Added conditional #undef jmpbuf in pngtest.c to undo #define in AIX headers. - Added scripts/makefile.nommx - -Version 1.2.15rc3 [December 25, 2006] - Fixed shared library numbering error that was introduced in 1.2.15beta6. - -Version 1.2.15rc4 [December 27, 2006] - Fixed handling of rgb_to_gray when png_ptr->color.gray isn't set. - -Version 1.2.15rc5 [December 31, 2006] - Revised handling of rgb_to_gray. - -Version 1.2.15 [January 5, 2007] - Added some (unsigned long) typecasts in pngtest.c to avoid printing errors. - -Version 1.2.16beta1 [January 6, 2007] - Fix bugs in makefile.nommx - -Version 1.2.16beta2 [January 16, 2007] - Revised scripts/CMakeLists.txt - -Version 1.2.16 [January 31, 2007] - No changes. - -Version 1.2.17beta1 [March 6, 2007] - Revised scripts/CMakeLists.txt to install both shared and static libraries. - Deleted a redundant line from pngset.c. - -Version 1.2.17beta2 [April 26, 2007] - Relocated misplaced test for png_ptr == NULL in pngpread.c - Change "==" to "&" for testing PNG_RGB_TO_GRAY_ERR & PNG_RGB_TO_GRAY_WARN - flags. - Changed remaining instances of PNG_ASSEMBLER_* to PNG_MMX_* - Added pngerror() when write_IHDR fails in deflateInit2(). - Added "const" to some array declarations. - Mention examples of libpng usage in the libpng*.txt and libpng.3 documents. - -Version 1.2.17rc1 [May 4, 2007] - No changes. - -Version 1.2.17rc2 [May 8, 2007] - Moved several PNG_HAVE_* macros out of PNG_INTERNAL because applications - calling set_unknown_chunk_location() need them. - Changed transformation flag from PNG_EXPAND_tRNS to PNG_EXPAND in - png_set_expand_gray_1_2_4_to_8(). - Added png_ptr->unknown_chunk to hold working unknown chunk data, so it - can be free'ed in case of error. Revised unknown chunk handling in - pngrutil.c and pngpread.c to use this structure. - -Version 1.2.17rc3 [May 8, 2007] - Revised symbol-handling in configure script. - -Version 1.2.17rc4 [May 10, 2007] - Revised unknown chunk handling to avoid storing unknown critical chunks. - -Version 1.0.25 [May 15, 2007] -Version 1.2.17 [May 15, 2007] - Added "png_ptr->num_trans=0" before error return in png_handle_tRNS, - to eliminate a vulnerability (CVE-2007-2445, CERT VU#684664) - -Version 1.0.26 [May 15, 2007] -Version 1.2.18 [May 15, 2007] - Reverted the libpng-1.2.17rc3 change to symbol-handling in configure script - -Version 1.2.19beta1 [May 18, 2007] - Changed "const static" to "static PNG_CONST" everywhere, mostly undoing - change of libpng-1.2.17beta2. Changed other "const" to "PNG_CONST" - Changed some handling of unused parameters, to avoid compiler warnings. - "if (unused == NULL) return;" becomes "unused = unused". - -Version 1.2.19beta2 [May 18, 2007] - Only use the valid bits of tRNS value in png_do_expand() (Brian Cartier) - -Version 1.2.19beta3 [May 19, 2007] - Add some "png_byte" typecasts in png_check_keyword() and write new_key - instead of key in zTXt chunk (Kevin Ryde). - -Version 1.2.19beta4 [May 21, 2007] - Add png_snprintf() function and use it in place of sprint() for improved - defense against buffer overflows. - -Version 1.2.19beta5 [May 21, 2007] - Fixed png_handle_tRNS() to only use the valid bits of tRNS value. - Changed handling of more unused parameters, to avoid compiler warnings. - Removed some PNG_CONST in pngwutil.c to avoid compiler warnings. - -Version 1.2.19beta6 [May 22, 2007] - Added some #ifdef PNG_MMX_CODE_SUPPORTED where needed in pngvcrd.c - Added a special "_MSC_VER" case that defines png_snprintf to _snprintf - -Version 1.2.19beta7 [May 22, 2007] - Squelched png_squelch_warnings() in pnggccrd.c and added - an #ifdef PNG_MMX_CODE_SUPPORTED block around the declarations that caused - the warnings that png_squelch_warnings was squelching. - -Version 1.2.19beta8 [May 22, 2007] - Removed __MMX__ from test in pngconf.h. - -Version 1.2.19beta9 [May 23, 2007] - Made png_squelch_warnings() available via PNG_SQUELCH_WARNINGS macro. - Revised png_squelch_warnings() so it might work. - Updated makefile.sgcc and makefile.solaris; added makefile.solaris-x86. - -Version 1.2.19beta10 [May 24, 2007] - Resquelched png_squelch_warnings(), use "__attribute__((used))" instead. - -Version 1.4.0beta1 [April 20, 2006] - Enabled iTXt support (changes png_struct, thus requires so-number change). - Cleaned up PNG_ASSEMBLER_CODE_SUPPORTED vs PNG_MMX_CODE_SUPPORTED - Eliminated PNG_1_0_X and PNG_1_2_X macros. - Removed deprecated functions png_read_init, png_write_init, png_info_init, - png_permit_empty_plte, png_set_gray_1_2_4_to_8, png_check_sig, and - removed the deprecated macro PNG_MAX_UINT. - Moved "PNG_INTERNAL" parts of png.h and pngconf.h into pngintrn.h - Removed many WIN32_WCE #ifdefs (Cosmin). - Reduced dependency on C-runtime library when on Windows (Simon-Pierre) - Replaced sprintf() with png_sprintf() (Simon-Pierre) - -Version 1.4.0beta2 [April 20, 2006] - Revised makefiles and configure to avoid making links to libpng.so.* - Moved some leftover MMX-related defines from pngconf.h to pngintrn.h - Updated scripts/pngos2.def, pngw32.def, and projects/wince/png32ce.def - -Version 1.4.0beta3 [May 10, 2006] - Updated scripts/pngw32.def to comment out MMX functions. - Added PNG_NO_GET_INT_32 and PNG_NO_SAVE_INT_32 macros. - Scripts/libpng.pc.in contained "configure" style version info and would - not work with makefiles. - Revised pngconf.h and added pngconf.h.in, so makefiles and configure can - pass defines to libpng and applications. - -Version 1.4.0beta4 [May 11, 2006] - Revised configure.ac, Makefile.am, and many of the makefiles to write - their defines in pngconf.h. - -Version 1.4.0beta5 [May 15, 2006] - Added a missing semicolon in Makefile.am and Makefile.in - Deleted extraneous square brackets from configure.ac - -Version 1.4.0beta6 [June 2, 2006] - Increased sprintf buffer from 50 to 52 chars in pngrutil.c to avoid - buffer overflow. - Changed sonum from 0 to 1. - Removed unused prototype for png_check_sig() from png.h - -Version 1.4.0beta7 [June 16, 2006] - Exported png_write_sig (Cosmin). - Optimized buffer in png_handle_cHRM() (Cosmin). - Set pHYs = 2835 x 2835 pixels per meter, and added - sCAL = 0.352778e-3 x 0.352778e-3 meters, in pngtest.png (Cosmin). - Added png_set_benign_errors(), png_benign_error(), png_chunk_benign_error(). - Added typedef for png_int_32 and png_uint_32 on 64-bit systems. - Added "(unsigned long)" typecast on png_uint_32 variables in printf lists. - -Version 1.4.0beta8 [June 22, 2006] - Added demonstration of user chunk support in pngtest.c, to support the - public sTER chunk and a private vpAg chunk. - -Version 1.4.0beta9 [July 3, 2006] - Removed ordinals from scripts/pngw32.def and removed png_info_int and - png_set_gray_1_2_4_to_8 entries. - Inline call of png_get_uint_32() in png_get_uint_31(). - Use png_get_uint_31() to get vpAg width and height in pngtest.c - Removed WINCE and Netware projects. - Removed standalone Y2KINFO file. - -Version 1.4.0beta10 [July 12, 2006] - Eliminated automatic copy of pngconf.h to pngconf.h.in from configure and - some makefiles, because it was not working reliably. Instead, distribute - pngconf.h.in along with pngconf.h and cause configure and some of the - makefiles to update pngconf.h from pngconf.h.in. - Added pngconf.h to DEPENDENCIES in Makefile.am - -Version 1.4.0beta11 [August 19, 2006] - Removed AC_FUNC_MALLOC from configure.ac. - Added a warning when writing iCCP profile with mismatched profile length. - Patched pnggccrd.c to assemble on x86_64 platforms. - Moved chunk header reading into a separate function png_read_chunk_header() - in pngrutil.c. The chunk header (len+sig) is now serialized in a single - operation (Cosmin). - Implemented support for I/O states. Added png_ptr member io_state, and - functions png_get_io_chunk_name() and png_get_io_state() in pngget.c - (Cosmin). - Added png_get_io_chunk_name and png_get_io_state to scripts/*.def (Cosmin). - Renamed scripts/pngw32.* to scripts/pngwin.* (Cosmin). - Removed the include directories and libraries from CFLAGS and LDFLAGS - in scripts/makefile.gcc (Cosmin). - Used png_save_uint_32() to set vpAg width and height in pngtest.c (Cosmin). - Cast to proper type when getting/setting vpAg units in pngtest.c (Cosmin). - Added pngintrn.h to the Visual C++ projects (Cosmin). - Removed scripts/list (Cosmin). - Updated copyright year in scripts/pngwin.def (Cosmin). - Removed PNG_TYPECAST_NULL and used standard NULL consistently (Cosmin). - Disallowed the user to redefine png_size_t, and enforced a consistent use - of png_size_t across libpng (Cosmin). - Changed the type of png_ptr->rowbytes, PNG_ROWBYTES() and friends - to png_size_t (Cosmin). - Removed png_convert_size() and replaced png_sizeof with sizeof (Cosmin). - Removed some unnecessary type casts (Cosmin). - Changed prototype of png_get_compression_buffer_size() and - png_set_compression_buffer_size() to work with png_size_t instead of - png_uint_32 (Cosmin). - Removed png_memcpy_check() and png_memset_check() (Cosmin). - Fixed a typo (png_byte --> png_bytep) in libpng.3 and libpng.txt (Cosmin). - Clarified that png_zalloc() does not clear the allocated memory, - and png_zalloc() and png_zfree() cannot be PNGAPI (Cosmin). - Renamed png_mem_size_t to png_alloc_size_t, fixed its definition in - pngconf.h, and used it in all memory allocation functions (Cosmin). - Renamed pngintrn.h to pngpriv.h, added a comment at the top of the file - mentioning that the symbols declared in that file are private, and - updated the scripts and the Visual C++ projects accordingly (Cosmin). - Removed circular references between pngconf.h and pngconf.h.in in - scripts/makefile.vc*win32 (Cosmin). - Removing trailing '.' from the warning and error messages (Cosmin). - Added pngdefs.h that is built by makefile or configure, instead of - pngconf.h.in (Glenn). - Detect and fix attempt to write wrong iCCP profile length. - -Version 1.4.0beta12 [October 19, 2006] - Changed "logical" to "bitwise" in the documentation. - Work around Intel-Mac compiler bug by setting PNG_NO_MMX_CODE in pngconf.h - Add a typecast to stifle compiler warning in pngrutil.c - -Version 1.4.0beta13 [November 10, 2006] - Fix potential buffer overflow in sPLT chunk handler. - Fix Makefile.am to not try to link to noexistent files. - -Version 1.4.0beta14 [November 15, 2006] - Check all exported functions for NULL png_ptr. - -Version 1.4.0beta15 [November 17, 2006] - Relocated two misplaced tests for NULL png_ptr. - Built Makefile.in with automake-1.9.6 instead of 1.9.2. - Build configure with autoconf-2.60 instead of 2.59 - Add "install: all" in Makefile.am so "configure; make install" will work. - -Version 1.4.0beta16 [November 17, 2006] - Added a typecast in png_zalloc(). - -Version 1.4.0beta17 [December 4, 2006] - Changed "new_key[79] = '\0';" to "(*new_key)[79] = '\0';" in pngwutil.c - Add "png_bytep" typecast to profile while calculating length in pngwutil.c - -Version 1.4.0beta18 [December 7, 2006] - Added scripts/CMakeLists.txt - -Version 1.4.0beta19 [May 16, 2007] - Revised scripts/CMakeLists.txt - Rebuilt configure and Makefile.in with newer tools. - Added conditional #undef jmpbuf in pngtest.c to undo #define in AIX headers. - Added scripts/makefile.nommx - -Version 1.4.0beta20 [July 9, 2008] - Moved several PNG_HAVE_* macros from pngpriv.h to png.h because applications - calling set_unknown_chunk_location() need them. - Moved several macro definitions from pngpriv.h to pngconf.h - Merge with changes to the 1.2.X branch, as of 1.2.30beta04. - Deleted all use of the MMX assembler code and Intel-licensed optimizations. - Revised makefile.mingw - -Version 1.4.0beta21 [July 21, 2008] - Moved local array "chunkdata" from pngrutil.c to the png_struct, so - it will be freed by png_read_destroy() in case of a read error (Kurt - Christensen). - -Version 1.4.0beta22 [July 21, 2008] - Change "purpose" and "buffer" to png_ptr->chunkdata to avoid memory leaking. - -Version 1.4.0beta23 [July 22, 2008] - Change "chunkdata = NULL" to "png_ptr->chunkdata = NULL" several places in - png_decompress_chunk(). - -Version 1.4.0beta24 [July 25, 2008] - Change all remaining "chunkdata" to "png_ptr->chunkdata" in - png_decompress_chunk(), and remove "chunkdata" from parameter list. - Put a call to png_check_chunk_name() in png_read_chunk_header(). - Revised png_check_chunk_name() to reject a name with a lowercase 3rd byte. - Removed two calls to png_check_chunk_name() occurring later in the process. - Define PNG_NO_ERROR_NUMBERS by default in pngconf.h - -Version 1.4.0beta25 [July 30, 2008] - Added a call to png_check_chunk_name() in pngpread.c - Reverted png_check_chunk_name() to accept a name with a lowercase 3rd byte. - Added png_push_have_buffer() function to pngpread.c - Eliminated PNG_BIG_ENDIAN_SUPPORTED and associated png_get_* macros. - Made inline expansion of png_get_*() optional with PNG_USE_READ_MACROS. - Eliminated all PNG_USELESS_TESTS and PNG_CORRECT_PALETTE_SUPPORTED code. - Synced contrib directory and configure files with libpng-1.2.30beta06. - Eliminated no-longer-used pngdefs.h (but it's still built in the makefiles) - Relocated a misplaced "#endif /* PNG_NO_WRITE_FILTER */" in pngwutil.c - -Version 1.4.0beta26 [August 4, 2008] - Removed png_push_have_buffer() function in pngpread.c. It increased the - compiled library size slightly. - Changed "-Wall" to "-W -Wall" in the CFLAGS in all makefiles (Cosmin Truta) - Declared png_ptr "volatile" in pngread.c and pngwrite.c to avoid warnings. - Updated contrib/visupng/cexcept.h to version 2.0.1 - Added PNG_LITERAL_CHARACTER macros for #, [, and ]. - -Version 1.4.0beta27 [August 5, 2008] - Revised usage of PNG_LITERAL_SHARP in pngerror.c. - Moved newline character from individual png_debug messages into the - png_debug macros. - Allow user to #define their own png_debug, png_debug1, and png_debug2. - -Version 1.4.0beta28 [August 5, 2008] - Revised usage of PNG_LITERAL_SHARP in pngerror.c. - Added PNG_STRING_NEWLINE macro - -Version 1.4.0beta29 [August 9, 2008] - Revised usage of PNG_STRING_NEWLINE to work on non-ISO compilers. - Added PNG_STRING_COPYRIGHT macro. - Added non-ISO versions of png_debug macros. - -Version 1.4.0beta30 [August 14, 2008] - Added premultiplied alpha feature (Volker Wiendl). - -Version 1.4.0beta31 [August 18, 2008] - Moved png_set_premultiply_alpha from pngtrans.c to pngrtran.c - Removed extra crc check at the end of png_handle_cHRM(). Bug introduced - in libpng-1.4.0beta20. - -Version 1.4.0beta32 [August 19, 2008] - Added PNG_WRITE_FLUSH_SUPPORTED block around new png_flush() call. - Revised PNG_NO_STDIO version of png_write_flush() - -Version 1.4.0beta33 [August 20, 2008] - Added png_get|set_chunk_cache_max() to limit the total number of sPLT, - text, and unknown chunks that can be stored. - -Version 1.4.0beta34 [September 6, 2008] - Shortened tIME_string to 29 bytes in pngtest.c - Fixed off-by-one error introduced in png_push_read_zTXt() function in - libpng-1.2.30beta04/pngpread.c (Harald van Dijk) - -Version 1.4.0beta35 [October 6, 2008] - Changed "trans_values" to "trans_color". - Changed so-number from 0 to 14. Some OS do not like 0. - Revised makefile.darwin to fix shared library numbering. - Change png_set_gray_1_2_4_to_8() to png_set_expand_gray_1_2_4_to_8() - in example.c (debian bug report) - -Version 1.4.0beta36 [October 25, 2008] - Sync with tEXt vulnerability fix in libpng-1.2.33rc02. - -Version 1.4.0beta37 [November 13, 2008] - Added png_check_cHRM in png.c and moved checking from pngget.c, pngrutil.c, - and pngwrite.c - -Version 1.4.0beta38 [November 22, 2008] - Added check for zero-area RGB cHRM triangle in png_check_cHRM() and - png_check_cHRM_fixed(). - -Version 1.4.0beta39 [November 23, 2008] - Revised png_warning() to write its message on standard output by default - when warning_fn is NULL. - -Version 1.4.0beta40 [November 24, 2008] - Eliminated png_check_cHRM(). Instead, always use png_check_cHRM_fixed(). - In png_check_cHRM_fixed(), ensure white_y is > 0, and removed redundant - check for all-zero coordinates that is detected by the triangle check. - -Version 1.4.0beta41 [November 26, 2008] - Fixed string vs pointer-to-string error in png_check_keyword(). - Rearranged test expressions in png_check_cHRM_fixed() to avoid internal - overflows. - Added PNG_NO_CHECK_cHRM conditional. - -Version 1.4.0beta42, 43 [December 1, 2008] - Merge png_debug with version 1.2.34beta04. - -Version 1.4.0beta44 [December 6, 2008] - Removed redundant check for key==NULL before calling png_check_keyword() - to ensure that new_key gets initialized and removed extra warning - (Merge with version 1.2.34beta05 -- Arvan Pritchard). - -Version 1.4.0beta45 [December 9, 2008] - In png_write_png(), respect the placement of the filler bytes in an earlier - call to png_set_filler() (Jim Barry). - -Version 1.4.0beta46 [December 10, 2008] - Undid previous change and added PNG_TRANSFORM_STRIP_FILLER_BEFORE and - PNG_TRANSFORM_STRIP_FILLER_AFTER conditionals and deprecated - PNG_TRANSFORM_STRIP_FILLER (Jim Barry). - -Version 1.4.0beta47 [December 15, 2008] - Support for dithering was disabled by default, because it has never - been well tested and doesn't work very well. The code has not - been removed, however, and can be enabled by building libpng with - PNG_READ_DITHER_SUPPORTED defined. - -Version 1.4.0beta48 [February 14, 2009] - Added new exported function png_calloc(). - Combined several instances of png_malloc(); png_memset() into png_calloc(). - Removed prototype for png_freeptr() that was added in libpng-1.4.0beta24 - but was never defined. - -Version 1.4.0beta49 [February 28, 2009] - Added png_fileno() macro to pngconf.h, used in pngwio.c - Corrected order of #ifdef's in png_debug definition in png.h - Fixed bug introduced in libpng-1.4.0beta48 with the memset arguments - for pcal_params. - Fixed order of #ifdef directives in the png_debug defines in png.h - (bug introduced in libpng-1.2.34/1.4.0beta29). - Revised comments in png_set_read_fn() and png_set_write_fn(). - -Version 1.4.0beta50 [March 18, 2009] - Use png_calloc() instead of png_malloc() to allocate big_row_buf when - reading an interlaced file, to avoid a possible UMR. - Undid revision of PNG_NO_STDIO version of png_write_flush(). Users - having trouble with fflush() can build with PNG_NO_WRITE_FLUSH defined - or supply their own flush_fn() replacement. - Revised libpng*.txt and png.h documentation about use of png_write_flush() - and png_set_write_fn(). - Removed fflush() from pngtest.c. - Added "#define PNG_NO_WRITE_FLUSH" to contrib/pngminim/encoder/pngusr.h - -Version 1.4.0beta51 [March 21, 2009] - Removed new png_fileno() macro from pngconf.h . - -Version 1.4.0beta52 [March 27, 2009] - Relocated png_do_chop() ahead of building gamma tables in pngrtran.c - This avoids building 16-bit gamma tables unnecessarily. - Removed fflush() from pngtest.c. - Added "#define PNG_NO_WRITE_FLUSH" to contrib/pngminim/encoder/pngusr.h - Added a section on differences between 1.0.x and 1.2.x to libpng.3/libpng.txt - -Version 1.4.0beta53 [April 1, 2009] - Removed some remaining MMX macros from pngpriv.h - Fixed potential memory leak of "new_name" in png_write_iCCP() (Ralph Giles) - -Version 1.4.0beta54 [April 13, 2009] - Added "ifndef PNG_SKIP_SETJMP_CHECK" block in pngconf.h to allow - application code writers to bypass the check for multiple inclusion - of setjmp.h when they know that it is safe to ignore the situation. - Eliminated internal use of setjmp() in pngread.c and pngwrite.c - Reordered ancillary chunks in pngtest.png to be the same as what - pngtest now produces, and made some cosmetic changes to pngtest output. - Eliminated deprecated png_read_init_3() and png_write_init_3() functions. - -Version 1.4.0beta55 [April 15, 2009] - Simplified error handling in pngread.c and pngwrite.c by putting - the new png_read_cleanup() and png_write_cleanup() functions inline. - -Version 1.4.0beta56 [April 25, 2009] - Renamed "user_chunk_data" to "my_user_chunk_data" in pngtest.c to suppress - "shadowed declaration" warning from gcc-4.3.3. - Renamed "gamma" to "png_gamma" in pngset.c to avoid "shadowed declaration" - warning about a global "gamma" variable in math.h on some platforms. - -Version 1.4.0beta57 [May 2, 2009] - Removed prototype for png_freeptr() that was added in libpng-1.4.0beta24 - but was never defined (again). - Rebuilt configure scripts with autoconf-2.63 instead of 2.62 - Removed pngprefs.h and MMX from makefiles - -Version 1.4.0beta58 [May 14, 2009] - Changed pngw32.def to pngwin.def in makefile.mingw (typo was introduced - in beta57). - Clarified usage of sig_bit versus sig_bit_p in example.c (Vincent Torri) - -Version 1.4.0beta59 [May 15, 2009] - Reformated sources in libpng style (3-space intentation, comment format) - Fixed typo in libpng docs (PNG_FILTER_AVE should be PNG_FILTER_AVG) - Added sections about the git repository and our coding style to the - documentation - Relocated misplaced #endif in pngwrite.c, sCAL chunk handler. - -Version 1.4.0beta60 [May 19, 2009] - Conditionally compile png_read_finish_row() which is not used by - progressive readers. - Added contrib/pngminim/preader to demonstrate building minimal progressive - decoder, based on contrib/gregbook with embedded libpng and zlib. - -Version 1.4.0beta61 [May 20, 2009] - In contrib/pngminim/*, renamed "makefile.std" to "makefile", since there - is only one makefile in those directories, and revised the README files - accordingly. - More reformatting of comments, mostly to capitalize sentences. - -Version 1.4.0beta62 [June 2, 2009] - Added "#define PNG_NO_WRITE_SWAP" to contrib/pngminim/encoder/pngusr.h - and "define PNG_NO_READ_SWAP" to decoder/pngusr.h and preader/pngusr.h - Reformatted several remaining "else statement" into two lines. - Added a section to the libpng documentation about using png_get_io_ptr() - in configure scripts to detect the presence of libpng. - -Version 1.4.0beta63 [June 15, 2009] - Revised libpng*.txt and libpng.3 to mention calling png_set_IHDR() - multiple times and to specify the sample order in the tRNS chunk, - because the ISO PNG specification has a typo in the tRNS table. - Changed several PNG_UNKNOWN_CHUNK_SUPPORTED to - PNG_HANDLE_AS_UNKNOWN_SUPPORTED, to make the png_set_keep mechanism - available for ignoring known chunks even when not saving unknown chunks. - Adopted preference for consistent use of "#ifdef" and "#ifndef" versus - "#if defined()" and "if !defined()" where possible. - -Version 1.4.0beta64 [June 24, 2009] - Eliminated PNG_LEGACY_SUPPORTED code. - Moved the various unknown chunk macro definitions outside of the - PNG_READ|WRITE_ANCILLARY_CHUNK_SUPPORTED blocks. - -Version 1.4.0beta65 [June 26, 2009] - Added a reference to the libpng license in each file. - -Version 1.4.0beta66 [June 27, 2009] - Refer to the libpng license instead of the libpng license in each file. - -Version 1.4.0beta67 [July 6, 2009] - Relocated INVERT_ALPHA within png_read_png() and png_write_png(). - Added high-level API transform PNG_TRANSFORM_GRAY_TO_RGB. - Added an "xcode" project to the projects directory (Alam Arias). - -Version 1.4.0beta68 [July 19, 2009] - Avoid some tests in filter selection in pngwutil.c - -Version 1.4.0beta69 [July 25, 2009] - Simplified the new filter-selection test. This runs faster in the - common "PNG_ALL_FILTERS" and PNG_FILTER_NONE cases. - Removed extraneous declaration from the new call to png_read_gray_to_rgb() - (bug introduced in libpng-1.4.0beta67). - Fixed up xcode project (Alam Arias) - Added a prototype for png_64bit_product() in png.c - -Version 1.4.0beta70 [July 27, 2009] - Avoid a possible NULL dereference in debug build, in png_set_text_2(). - (bug introduced in libpng-0.95, discovered by Evan Rouault) - -Version 1.4.0beta71 [July 29, 2009] - Rebuilt configure scripts with autoconf-2.64. - -Version 1.4.0beta72 [August 1, 2009] - Replaced *.tar.lzma with *.tar.xz in distribution. Get the xz codec - from . - -Version 1.4.0beta73 [August 1, 2009] - Reject attempt to write iCCP chunk with negative embedded profile length - (JD Chen) (CVE-2009-5063). - -Version 1.4.0beta74 [August 8, 2009] - Changed png_ptr and info_ptr member "trans" to "trans_alpha". - -Version 1.4.0beta75 [August 21, 2009] - Removed an extra png_debug() recently added to png_write_find_filter(). - Fixed incorrect #ifdef in pngset.c regarding unknown chunk support. - -Version 1.4.0beta76 [August 22, 2009] - Moved an incorrectly located test in png_read_row() in pngread.c - -Version 1.4.0beta77 [August 27, 2009] - Removed lpXYZ.tar.bz2 (with CRLF), KNOWNBUG, libpng-x.y.z-KNOWNBUG.txt, - and the "noconfig" files from the distribution. - Moved CMakeLists.txt from scripts into the main libpng directory. - Various bugfixes and improvements to CMakeLists.txt (Philip Lowman) - -Version 1.4.0beta78 [August 31, 2009] - Converted all PNG_NO_* tests to PNG_*_SUPPORTED everywhere except pngconf.h - Eliminated PNG_NO_FREE_ME and PNG_FREE_ME_SUPPORTED macros. - Use png_malloc plus a loop instead of png_calloc() to initialize - row_pointers in png_read_png(). - -Version 1.4.0beta79 [September 1, 2009] - Eliminated PNG_GLOBAL_ARRAYS and PNG_LOCAL_ARRAYS; always use local arrays. - Eliminated PNG_CALLOC_SUPPORTED macro and always provide png_calloc(). - -Version 1.4.0beta80 [September 17, 2009] - Removed scripts/libpng.icc - Changed typecast of filler from png_byte to png_uint_16 in png_set_filler(). - (Dennis Gustafsson) - Fixed typo introduced in beta78 in pngtest.c ("#if def " should be "#ifdef ") - -Version 1.4.0beta81 [September 23, 2009] - Eliminated unused PNG_FLAG_FREE_* defines from pngpriv.h - Expanded TAB characters in pngrtran.c - Removed PNG_CONST from all "PNG_CONST PNG_CHNK" declarations to avoid - compiler complaints about doubly declaring things "const". - Changed all "#if [!]defined(X)" to "if[n]def X" where possible. - Eliminated unused png_ptr->row_buf_size - -Version 1.4.0beta82 [September 25, 2009] - Moved redundant IHDR checking into new png_check_IHDR() in png.c - and report all errors found in the IHDR data. - Eliminated useless call to png_check_cHRM() from pngset.c - -Version 1.4.0beta83 [September 25, 2009] - Revised png_check_IHDR() to eliminate bogus complaint about filter_type. - -Version 1.4.0beta84 [September 30, 2009] - Fixed some inconsistent indentation in pngconf.h - Revised png_check_IHDR() to add a test for width variable less than 32-bit. - -Version 1.4.0beta85 [October 1, 2009] - Revised png_check_IHDR() again, to check info_ptr members instead of - the contents of the returned parameters. - -Version 1.4.0beta86 [October 9, 2009] - Updated the "xcode" project (Alam Arias). - Eliminated a shadowed declaration of "pp" in png_handle_sPLT(). - -Version 1.4.0rc01 [October 19, 2009] - Trivial cosmetic changes. - -Version 1.4.0beta87 [October 30, 2009] - Moved version 1.4.0 back into beta. - -Version 1.4.0beta88 [October 30, 2009] - Revised libpng*.txt section about differences between 1.2.x and 1.4.0 - because most of the new features have now been ported back to 1.2.41 - -Version 1.4.0beta89 [November 1, 2009] - More bugfixes and improvements to CMakeLists.txt (Philip Lowman) - Removed a harmless extra png_set_invert_alpha() from pngwrite.c - Apply png_user_chunk_cache_max within png_decompress_chunk(). - Merged libpng-1.2.41.txt with libpng-1.4.0.txt where appropriate. - -Version 1.4.0beta90 [November 2, 2009] - Removed all remaining WIN32_WCE #ifdefs except those involving the - time.h "tm" structure - -Version 1.4.0beta91 [November 3, 2009] - Updated scripts/pngw32.def and projects/wince/png32ce.def - Copied projects/wince/png32ce.def to the scripts directory. - Added scripts/makefile.wce - Patched ltmain.sh for wince support. - Added PNG_CONVERT_tIME_SUPPORTED macro. - -Version 1.4.0beta92 [November 4, 2009] - Make inclusion of time.h in pngconf.h depend on PNG_CONVERT_tIME_SUPPORTED - Make #define PNG_CONVERT_tIME_SUPPORTED depend on PNG_WRITE_tIME_SUPPORTED - Revised libpng*.txt to describe differences from 1.2.40 to 1.4.0 (instead - of differences from 1.2.41 to 1.4.0) - -Version 1.4.0beta93 [November 7, 2009] - Added PNG_DEPSTRUCT, PNG_DEPRECATED, PNG_USE_RESULT, PNG_NORETURN, and - PNG_ALLOCATED macros to detect deprecated direct access to the - png_struct or info_struct members and other deprecated usage in - applications (John Bowler). - Updated scripts/makefile* to add "-DPNG_CONFIGURE_LIBPNG" to CFLAGS, - to prevent warnings about direct access to png structs by libpng - functions while building libpng. They need to be tested, especially - those using compilers other than gcc. - Updated projects/visualc6 and visualc71 with "/d PNG_CONFIGURE_LIBPNG". - They should work but still need to be updated to remove - references to pnggccrd.c or pngvcrd.c and ASM building. - Added README.txt to the beos, cbuilder5, netware, and xcode projects warning - that they need to be updated, to remove references to pnggccrd.c and - pngvcrd.c and to depend on pngpriv.h - Removed three direct references to read_info_ptr members in pngtest.c - that were detected by the new PNG_DEPSTRUCT macro. - Moved the png_debug macro definitions and the png_read_destroy(), - png_write_destroy() and png_far_to_near() prototypes from png.h - to pngpriv.h (John Bowler) - Moved the synopsis lines for png_read_destroy(), png_write_destroy() - png_debug(), png_debug1(), and png_debug2() from libpng.3 to libpngpf.3. - -Version 1.4.0beta94 [November 9, 2009] - Removed the obsolete, unused pnggccrd.c and pngvcrd.c files. - Updated CMakeLists.txt to add "-DPNG_CONFIGURE_LIBPNG" to the definitions. - Removed dependency of pngtest.o on pngpriv.h in the makefiles. - Only #define PNG_DEPSTRUCT, etc. in pngconf.h if not already defined. - -Version 1.4.0beta95 [November 10, 2009] - Changed png_check_sig() to !png_sig_cmp() in contrib programs. - Added -DPNG_CONFIGURE_LIBPNG to contrib/pngminm/*/makefile - Changed png_check_sig() to !png_sig_cmp() in contrib programs. - Corrected the png_get_IHDR() call in contrib/gregbook/readpng2.c - Changed pngminim/*/gather.sh to stop trying to remove pnggccrd.c and pngvcrd.c - Added dependency on pngpriv.h in contrib/pngminim/*/makefile - -Version 1.4.0beta96 [November 12, 2009] - Renamed scripts/makefile.wce to scripts/makefile.cegcc - Revised Makefile.am to use libpng.sys while building libpng.so - so that only PNG_EXPORT functions are exported. - Removed the deprecated png_check_sig() function/macro. - Removed recently removed function names from scripts/*.def - Revised pngtest.png to put chunks in the same order written by pngtest - (evidently the same change made in libpng-1.0beta54 was lost). - Added PNG_PRIVATE macro definition in pngconf.h for possible future use. - -Version 1.4.0beta97 [November 13, 2009] - Restored pngtest.png to the libpng-1.4.0beta7 version. - Removed projects/beos and netware.txt; no one seems to be supporting them. - Revised Makefile.in - -Version 1.4.0beta98 [November 13, 2009] - Added the "xcode" project to zip distributions, - Fixed a typo in scripts/pngwin.def introduced in beta97. - -Version 1.4.0beta99 [November 14, 2009] - Moved libpng-config.in and libpng.pc-configure.in out of the scripts - directory, to libpng-config.in and libpng-pc.in, respectively, and - modified Makefile.am and configure.ac accordingly. Now "configure" - needs nothing from the "scripts" directory. - Avoid redefining PNG_CONST in pngconf.h - -Version 1.4.0beta100 [November 14, 2009] - Removed ASM builds from projects/visualc6 and projects/visualc71 - Removed scripts/makefile.nommx and makefile.vcawin32 - Revised CMakeLists.txt to account for new location of libpng-config.in - and libpng-pc.in - Updated INSTALL to reflect removal and relocation of files. - -Version 1.4.0beta101 [November 14, 2009] - Restored the binary files (*.jpg, *.png, some project files) that were - accidentally deleted from the zip and 7z distributions when the xcode - project was added. - -Version 1.4.0beta102 [November 18, 2009] - Added libpng-config.in and libpng-pc.in to the zip and 7z distributions. - Fixed a typo in projects/visualc6/pngtest.dsp, introduced in beta100. - Moved descriptions of makefiles and other scripts out of INSTALL into - scripts/README.txt - Updated the copyright year in scripts/pngwin.rc from 2006 to 2009. - -Version 1.4.0beta103 [November 21, 2009] - Removed obsolete comments about ASM from projects/visualc71/README_zlib.txt - Align row_buf on 16-byte boundary in memory. - Restored the PNG_WRITE_FLUSH_AFTER_IEND_SUPPORTED guard around the call - to png_flush() after png_write_IEND(). See 1.4.0beta32, 1.4.0beta50 - changes above and 1.2.30, 1.2.30rc01 and rc03 in 1.2.41 CHANGES. Someone - needs this feature. - Make the 'png_jmpbuf' macro expand to a call that records the correct - longjmp function as well as returning a pointer to the setjmp - jmp_buf buffer, and marked direct access to jmpbuf 'deprecated'. - (John Bowler) - -Version 1.4.0beta104 [November 22, 2009] - Removed png_longjmp_ptr from scripts/*.def and libpng.3 - Rebuilt configure scripts with autoconf-2.65 - -Version 1.4.0beta105 [November 25, 2009] - Use fast integer PNG_DIVIDE_BY_255() or PNG_DIVIDE_BY_65535() - to accomplish alpha premultiplication when - PNG_READ_COMPOSITE_NODIV_SUPPORTED is defined. - Changed "/255" to "/255.0" in background calculations to make it clear - that the 255 is used as a double. - -Version 1.4.0beta106 [November 27, 2009] - Removed premultiplied alpha feature. - -Version 1.4.0beta107 [December 4, 2009] - Updated README - Added "#define PNG_NO_PEDANTIC_WARNINGS" in the libpng source files. - Removed "-DPNG_CONFIGURE_LIBPNG" from the makefiles and projects. - Revised scripts/makefile.netbsd, makefile.openbsd, and makefile.sco - to put png.h and pngconf.h in $prefix/include, like the other scripts, - instead of in $prefix/include/libpng. Also revised makefile.sco - to put them in $prefix/include/libpng15 instead of in - $prefix/include/libpng/libpng15. - -Version 1.4.0beta108 [December 11, 2009] - Removed leftover "-DPNG_CONFIGURE_LIBPNG" from contrib/pngminim/*/makefile - Relocated png_do_chop() to its original position in pngrtran.c; the - change in version 1.2.41beta08 caused transparency to be handled wrong - in some 16-bit datastreams (Yusaku Sugai). - -Version 1.4.0beta109 [December 13, 2009] - Added "bit_depth" parameter to the private png_build_gamma_table() function. - Pass bit_depth=8 to png_build_gamma_table() when bit_depth is 16 but the - PNG_16_TO_8 transform has been set, to avoid unnecessary build of 16-bit - tables. - -Version 1.4.0rc02 [December 20, 2009] - Declared png_cleanup_needed "volatile" in pngread.c and pngwrite.c - -Version 1.4.0rc03 [December 22, 2009] - Renamed libpng-pc.in back to libpng.pc.in and revised CMakeLists.txt - (revising the change in 1.4.0beta99) - -Version 1.4.0rc04 [December 25, 2009] - Swapped PNG_UNKNOWN_CHUNKS_SUPPORTED and PNG_HANDLE_AS_UNKNOWN_SUPPORTED - in pngset.c to be consistent with other changes in version 1.2.38. - -Version 1.4.0rc05 [December 25, 2009] - Changed "libpng-pc.in" to "libpng.pc.in" in configure.ac, configure, and - Makefile.in to be consistent with changes in libpng-1.4.0rc03 - -Version 1.4.0rc06 [December 29, 2009] - Reverted the gamma_table changes from libpng-1.4.0beta109. - Fixed some indentation errors. - -Version 1.4.0rc07 [January 1, 2010] - Revised libpng*.txt and libpng.3 about 1.2.x->1.4.x differences. - Use png_calloc() instead of png_malloc(); png_memset() in pngrutil.c - Update copyright year to 2010. - -Version 1.4.0rc08 [January 2, 2010] - Avoid deprecated references to png_ptr-io_ptr and png_ptr->error_ptr - in pngtest.c - -Version 1.4.0 [January 3, 2010] - No changes. - -Version 1.4.1beta01 [January 8, 2010] - Updated CMakeLists.txt for consistent indentation and to avoid an - unclosed if-statement warning (Philip Lowman). - Revised Makefile.am and Makefile.in to remove references to Y2KINFO, - KNOWNBUG, and libpng.la (Robert Schwebel). - Revised the makefiles to install the same files and symbolic - links as configure, except for libpng.la and libpng14.la. - Make png_set|get_compression_buffer_size() available even when - PNG_WRITE_SUPPORTED is not enabled. - Revised Makefile.am and Makefile.in to simplify their maintenance. - Revised scripts/makefile.linux to install a link to libpng14.so.14.1 - -Version 1.4.1beta02 [January 9, 2010] - Revised the rest of the makefiles to install a link to libpng14.so.14.1 - -Version 1.4.1beta03 [January 10, 2010] - Removed png_set_premultiply_alpha() from scripts/*.def - -Version 1.4.1rc01 [January 16, 2010] - No changes. - -Version 1.4.1beta04 [January 23, 2010] - Revised png_decompress_chunk() to improve speed and memory usage when - decoding large chunks. - Added png_set|get_chunk_malloc_max() functions. - -Version 1.4.1beta05 [January 26, 2010] - Relocated "int k" declaration in pngtest.c to minimize its scope. - -Version 1.4.1beta06 [January 28, 2010] - Revised png_decompress_chunk() to use a two-pass method suggested by - John Bowler. - -Version 1.4.1beta07 [February 6, 2010] - Folded some long lines in the source files. - Added defineable PNG_USER_CHUNK_CACHE_MAX, PNG_USER_CHUNK_MALLOC_MAX, - and a PNG_USER_LIMITS_SUPPORTED flag. - Eliminated use of png_ptr->irowbytes and reused the slot in png_ptr as - png_ptr->png_user_chunk_malloc_max. - Revised png_push_save_buffer() to do fewer but larger png_malloc() calls. - -Version 1.4.1beta08 [February 6, 2010] - Minor cleanup and updating of dates and copyright year. - -Version 1.5.0beta01 [February 7, 2010] - Moved declaration of png_struct into private pngstruct.h and png_info - into pnginfo.h - -Version 1.4.1beta09 and 1.5.0beta02 [February 7, 2010] - Reverted to original png_push_save_buffer() code. - -Version 1.4.1beta10 and 1.5.0beta03 [February 8, 2010] - Return allocated "old_buffer" in png_push_save_buffer() before - calling png_error(), to avoid a potential memory leak. - Updated configure script to use SO number 15. - -Version 1.5.0beta04 [February 9, 2010] - Removed malformed "incomplete struct declaration" of png_info from png.h - -Version 1.5.0beta05 [February 12, 2010] - Removed PNG_DEPSTRUCT markup in pngstruct.h and pnginfo.h, and undid the - linewrapping that it entailed. - Revised comments in pngstruct.h and pnginfo.h and added pointers to - the libpng license. - Changed PNG_INTERNAL to PNG_EXPOSE_INTERNAL_STRUCTURES - Removed the cbuilder5 project, which has not been updated to 1.4.0. - -Version 1.4.1beta12 and 1.5.0beta06 [February 14, 2010] - Fixed type declaration of png_get_chunk_malloc_max() in pngget.c (Daisuke - Nishikawa) - -Version 1.5.0beta07 [omitted] - -Version 1.5.0beta08 [February 19, 2010] - Changed #ifdef PNG_NO_STDIO_SUPPORTED to #ifdef PNG_NO_CONSOLE_IO_SUPPORTED - wherever png_snprintf() is used to construct error and warning messages. - Noted in scripts/makefile.mingw that it expects to be run under MSYS. - Removed obsolete unused MMX-querying support from contrib/gregbook - Added exported png_longjmp() function. - Removed the AIX redefinition of jmpbuf in png.h - Added -D_ALLSOURCE in configure.ac, makefile.aix, and CMakeLists.txt - when building on AIX. - -Version 1.5.0beta09 [February 19, 2010] - Removed -D_ALLSOURCE from configure.ac, makefile.aix, and CMakeLists.txt. - Changed the name of png_ptr->jmpbuf to png_ptr->png_jmpbuf in pngstruct.h - -Version 1.5.0beta10 [February 25, 2010] - Removed unused gzio.c from contrib/pngminim gather and makefile scripts - Removed replacement error handlers from contrib/gregbook. Because of - the new png_longjmp() function they are no longer needed. - -Version 1.5.0beta11 [March 6, 2010] - Removed checking for already-included setjmp.h from pngconf.h - Fixed inconsistent indentations and made numerous cosmetic changes. - Revised the "SEE ALSO" style of libpng.3, libpngpf.3, and png.5 - -Version 1.5.0beta12 [March 9, 2010] - Moved "#include png.h" inside pngpriv.h and removed "#include png.h" from - the source files, along with "#define PNG_EXPOSE_INTERNAL_STRUCTURES" - and "#define PNG_NO_PEDANTIC_WARNINGS" (John Bowler). - Created new pngdebug.h and moved debug definitions there. - -Version 1.5.0beta13 [March 10, 2010] - Protect pngstruct.h, pnginfo.h, and pngdebug.h from being included twice. - Revise the "#ifdef" blocks in png_inflate() so it will compile when neither - PNG_USER_CHUNK_MALLOC_MAX nor PNG_SET_CHUNK_MALLOC_LIMIT_SUPPORTED - is defined. - Removed unused png_measure_compressed_chunk() from pngpriv.h and libpngpf.3 - Moved the 'config.h' support from pngconf.h to pngpriv.h - Removed PNGAPI from the png_longjmp_ptr typedef. - Eliminated dependence of pngtest.c on the private pngdebug.h file. - Make all png_debug macros into *unterminated* statements or - expressions (i.e. a trailing ';' must always be added) and correct - the format statements in various png_debug messages. - -Version 1.5.0beta14 [March 14, 2010] - Removed direct access to png_ptr->io_ptr from the Windows code in pngtest.c - Revised Makefile.am to account for recent additions and replacements. - Corrected CE and OS/2 DEF files (scripts/png*def) for symbols removed and - added ordinal numbers to the Windows DEF file and corrected the duplicated - ordinal numbers on CE symbols that are commented out. - Added back in export symbols that can be present in the Windows build but - are disabled by default. - PNG_EXPORT changed to include an 'ordinal' field for DEF file generation. - PNG_CALLBACK added to make callback definitions uniform. PNGAPI split - into PNGCAPI (base C form), PNGAPI (exports) and PNGCBAPI (callbacks), - and appropriate changes made to all files. Cygwin builds re-hinged to - allow procedure call standard changes and to remove the need for the DEF - file (fixes build on Cygwin). - Enabled 'attribute' warnings that are relevant to library APIs and callbacks. - Changed rules for generation of the various symbol files and added a new - rule for a DEF file (which is also added to the distribution). - Updated the symbol file generation to stop it adding spurious spaces - to EOL (coming from preprocessor macro expansion). Added a facility - to join tokens in the output and rewrite *.dfn to use this. - Eliminated scripts/*.def in favor of libpng.def; updated projects/visualc71 - and removed scripts/makefile.cygwin. - Made PNG_BUILD_DLL safe: it can be set whenever a DLL is being built. - Removed the include of sys/types.h - apparently unnecessary now on the - platforms on which it happened (all but Mac OS and RISC OS). - Moved the Mac OS test into pngpriv.h (the only place it is used.) - -Version 1.5.0beta15 [March 17, 2010] - Added symbols.chk target to Makefile.am to validate the symbols in png.h - against the new DEF file scripts/symbols.def. - Changed the default DEF file back to pngwin.def. - Removed makefile.mingw. - Eliminated PNG_NO_EXTERN and PNG_ALL_EXTERN - -Version 1.5.0beta16 [April 1, 2010] - Make png_text_struct independent of PNG_iTXt_SUPPORTED, so that - fields are initialized in all configurations. The READ/WRITE - macros (PNG_(READ|WRITE)_iTXt_SUPPORTED) still function as - before to disable code to actually read or write iTXt chunks - and iTXt_SUPPORTED can be used to detect presence of either - read or write support (but it is probably better to check for - the one actually required - read or write.) - Combined multiple png_warning() calls for a single error. - Restored the macro definition of png_check_sig(). - -Version 1.5.0beta17 [April 17, 2010] - Added some "(long)" typecasts to printf calls in png_handle_cHRM(). - Documented the fact that png_set_dither() was disabled since libpng-1.4.0. - Reenabled png_set_dither() but renamed it to png_set_quantize() to reflect - more accurately what it actually does. At the same time, renamed - the PNG_DITHER_[RED,GREEN_BLUE]_BITS macros to - PNG_QUANTIZE_[RED,GREEN,BLUE]_BITS. - Added some "(long)" typecasts to printf calls in png_handle_cHRM(). - Freeze build-time only configuration in the build. - In all prior versions of libpng most configuration options - controlled by compiler #defines had to be repeated by the - application code that used libpng. This patch changes this - so that compilation options that can only be changed at build - time are frozen in the build. Options that are compiler - dependent (and those that are system dependent) are evaluated - each time - pngconf.h holds these. Options that can be changed - per-file in the application are in png.h. Frozen options are - in the new installed header file pnglibconf.h (John Bowler) - Removed the xcode project because it has not been updated to work - with libpng-1.5.0. - Removed the ability to include optional pngusr.h - -Version 1.5.0beta18 [April 17, 2010] - Restored the ability to include optional pngusr.h - Moved replacements for png_error() and png_warning() from the - contrib/pngminim project to pngerror.c, for use when warnings or - errors are disabled via PNG_NO_WARN or PNG_NO_ERROR_TEXT, to avoid - storing unneeded error/warning text. - Updated contrib/pngminim project to work with the new pnglibconf.h - Added some PNG_NO_* defines to contrib/pngminim/*/pngusr.h to save space. - -Version 1.5.0beta19 [April 24, 2010] - Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the functions - to read and write ints to be disabled independently of PNG_USE_READ_MACROS, - which allows libpng to be built with the functions even though the default - is to use the macros - this allows applications to choose at app build - time whether or not to use macros (previously impossible because the - functions weren't in the default build.) - Changed Windows calling convention back to __cdecl for API functions. - For Windows/x86 platforms only: - __stdcall is no longer needed for Visual Basic, so libpng-1.5.0 uses - __cdecl throughout (both API functions and callbacks) on Windows/x86 - platforms. - Replaced visualc6 and visualc71 projects with new vstudio project - Relaxed the overly-restrictive permissions of some files. - -Version 1.5.0beta20 [April 24, 2010] - Relaxed more overly-restrictive permissions of some files. - -Version 1.5.0beta21 [April 27, 2010] - Removed some unwanted binary bytes and changed CRLF to NEWLINE in the new - vstudio project files, and some trivial editing of some files in the - scripts directory. - Set PNG_NO_READ_BGR, PNG_NO_IO_STATE, and PNG_NO_TIME_RFC1123 in - contrib/pngminim/decoder/pngusr.h to make a smaller decoder application. - -Version 1.5.0beta22 [April 28, 2010] - Fixed dependencies of GET_INT_32 - it does not require READ_INT_FUNCTIONS - because it has a macro equivalent. - Improved the options.awk script; added an "everything off" option. - Revised contrib/pngminim to use the "everything off" option in pngusr.dfa. - -Version 1.5.0beta23 [April 29, 2010] - Corrected PNG_REMOVED macro to take five arguments. - The macro was documented with two arguments (name,ordinal), however - the symbol checking .dfn files assumed five arguments. The five - argument form seems more useful so it is changed to that. - Corrected PNG_UNKNOWN_CHUNKS_SUPPORTED to PNG_HANDLE_AS_UNKNOWN_SUPPORTED - in gregbook/readpng2.c - Corrected protection of png_get_user_transform_ptr. The API declaration in - png.h is removed if both READ and WRITE USER_TRANSFORM are turned off - but was left defined in pngtrans.c - Added logunsupported=1 to cause pnglibconf.h to document disabled options. - This makes the installed pnglibconf.h more readable but causes no - other change. The intention is that users of libpng will find it - easier to understand if an API they need is missing. - Include png_reset_zstream() in png.c only when PNG_READ_SUPPORTED is defined. - Removed dummy_inflate.c from contrib/pngminim/encoder - Removed contrib/pngminim/*/gather.sh; gathering is now done in the makefile. - -Version 1.5.0beta24 [May 7, 2010] - Use bitwise "&" instead of arithmetic mod in pngrutil.c calculation of the - offset of the png_ptr->rowbuf pointer into png_ptr->big_row_buf. - Added more blank lines for readability. - -Version 1.5.0beta25 [June 18, 2010] - In pngpread.c: png_push_have_row() add check for new_row > height - Removed the now-redundant check for out-of-bounds new_row from example.c - -Version 1.5.0beta26 [June 18, 2010] - In pngpread.c: png_push_process_row() add check for too many rows. - -Version 1.5.0beta27 [June 18, 2010] - Removed the check added in beta25 as it is now redundant. - -Version 1.5.0beta28 [June 20, 2010] - Rewrote png_process_IDAT_data to consistently treat extra data as warnings - and handle end conditions more cleanly. - Removed the new (beta26) check in png_push_process_row(). - -Version 1.5.0beta29 [June 21, 2010] - Revised scripts/options.awk to work on Sunos (but still doesn't work) - Added comment to options.awk and contrib/pngminim/*/makefile to try nawk. - -Version 1.5.0beta30 [June 22, 2010] - Stop memory leak when reading a malformed sCAL chunk. - -Version 1.5.0beta31 [June 26, 2010] - Revised pngpread.c patch of beta28 to avoid an endless loop. - Removed some trailing blanks. - -Version 1.5.0beta32 [June 26, 2010] - Removed leftover scripts/options.patch and scripts/options.rej - -Version 1.5.0beta33 [July 6, 3010] - Made FIXED and FLOATING options consistent in the APIs they enable and - disable. Corrected scripts/options.awk to handle both command line - options and options specified in the .dfa files. - Changed char *msg to PNG_CONST char *msg in pngrutil.c - Make png_set_sRGB_gAMA_and_cHRM set values using either the fixed or - floating point APIs, but not both. - Reversed patch to remove error handler when the jmp_buf is stored in the - main program structure, not the png_struct. - The error handler is needed because the default handler in libpng will - always use the jmp_buf in the library control structure; this is never - set. The gregbook code is a useful example because, even though it - uses setjmp/longjmp, it shows how error handling can be implemented - using control mechanisms not directly supported by libpng. The - technique will work correctly with mechanisms such as Microsoft - Structure Exceptions or C++ exceptions (compiler willing - note that gcc - does not by default support interworking of C and C++ error handling.) - Reverted changes to call png_longjmp in contrib/gregbook where it is not - appropriate. If mainprog->jmpbuf is used by setjmp, then png_longjmp - cannot be used. - Changed "extern PNG_EXPORT" to "PNG_EXPORT" in png.h (Jan Nijtmans) - Changed "extern" to "PNG_EXTERN" in pngpriv.h (except for the 'extern "C" {') - -Version 1.5.0beta34 [July 12, 2010] - Put #ifndef PNG_EXTERN, #endif around the define PNG_EXTERN in pngpriv.h - -Version 1.5.0beta35 [July 24, 2010] - Removed some newly-added TAB characters. - Added -DNO_PNG_SNPRINTF to CFLAGS in scripts/makefile.dj2 - Moved the definition of png_snprintf() outside of the enclosing - #ifdef blocks in pngconf.h - -Version 1.5.0beta36 [July 29, 2010] - Patches by John Bowler: - Fixed point APIs are now supported throughout (no missing APIs). - Internal fixed point arithmetic support exists for all internal floating - point operations. - sCAL validates the floating point strings it is passed. - Safe, albeit rudimentary, Watcom support is provided by PNG_API_RULE==2 - Two new APIs exist to get the number of passes without turning on the - PNG_INTERLACE transform and to get the number of rows in the current - pass. - A new test program, pngvalid.c, validates the gamma code. - Errors in the 16-bit gamma correction (overflows) have been corrected. - cHRM chunk testing is done consistently (previously the floating point - API bypassed it, because the test really didn't work on FP, now the test - is performed on the actual values to be stored in the PNG file so it - works in the FP case too.) - Most floating point APIs now simply call the fixed point APIs after - converting the values to the fixed point form used in the PNG file. - The standard headers no longer include zlib.h, which is currently only - required for pngstruct.h and can therefore be internal. - Revised png_get_int_32 to undo the PNG two's complement representation of - negative numbers. - -Version 1.5.0beta37 [July 30, 2010] - Added a typecast in png_get_int_32() in png.h and pngrutil.h to avoid - a compiler warning. - Replaced oFFs 0,0 with oFFs -10,20 in pngtest.png - -Version 1.5.0beta38 [July 31, 2010] - Implemented remaining "_fixed" functions. - Corrected a number of recently introduced warnings mostly resulting from - safe but uncast assignments to shorter integers. Also added a zlib - VStudio release library project because the latest zlib Official Windows - build does not include such a thing. - Revised png_get_int_16() to be similar to png_get_int_32(). - Restored projects/visualc71. - -Version 1.5.0beta39 [August 2, 2010] - VisualC/GCC warning fixes, VisualC build fixes - The changes include support for function attributes in VC in addition to - those already present in GCC - necessary because without these some - warnings are unavoidable. Fixes include signed/unsigned fixes in - pngvalid and checks with gcc -Wall -Wextra -Wunused. - VC requires function attributes on function definitions as well as - declarations, PNG_FUNCTION has been added to enable this and the - relevant function definitions changed. - -Version 1.5.0beta40 [August 6, 2010] - Correct use of _WINDOWS_ in pngconf.h - Removed png_mem_ #defines; they are no longer used. - Added the sRGB chunk to pngtest.png - -Version 1.5.0beta41 [August 11, 2010] - Added the cHRM chunk to pngtest.png - Don't try to use version-script with cygwin/mingw. - Revised contrib/gregbook to work under cygwin/mingw. - -Version 1.5.0beta42 [August 18, 2010] - Add .dll.a to the list of extensions to be symlinked by Makefile.am (Yaakov) - Made all API functions that have const arguments and constant string - literal pointers declare them (John Bowler). - -Version 1.5.0beta43 [August 20, 2010] - Removed spurious tabs, shorten long lines (no source change) - Also added scripts/chkfmt to validate the format of all the files that can - reasonably be validated (it is suggested to run "make distclean" before - checking, because some machine generated files have long lines.) - Reformatted the CHANGES file to be more consistent throughout. - Made changes to address various issues identified by GCC, mostly - signed/unsigned and shortening problems on assignment but also a few - difficult to optimize (for GCC) loops. - Fixed non-GCC fixed point builds. In png.c a declaration was misplaced - in an earlier update. Fixed to declare the auto variables at the head. - Use cexcept.h in pngvalid.c. - -Version 1.5.0beta44 [August 24, 2010] - Updated CMakeLists.txt to use CMAKE_INSTALL_LIBDIR variable; useful for - installing libpng in /usr/lib64 (Funda Wang). - Revised CMakeLists.txt to put the man pages in share/man/man* not man/man* - Revised CMakeLists.txt to make symlinks instead of copies when installing. - Changed PNG_LIB_NAME from pngNN to libpngNN in CMakeLists.txt (Philip Lowman) - Implemented memory checks within pngvalid - Reformatted/rearranged pngvalid.c to assist use of progressive reader. - Check interlaced images in pngvalid - Clarified pngusr.h comments in pnglibconf.dfa - Simplified the pngvalid error-handling code now that cexcept.h is in place. - Implemented progressive reader in pngvalid.c for standard tests - Implemented progressive read in pngvalid.c gamma tests - Turn on progressive reader in pngvalid.c by default and tidy code. - -Version 1.5.0beta45 [August 26, 2010] - Added an explicit make step to projects/vstudio for pnglibconf.h - Also corrected zlib.vcxproj into which Visual Studio had introduced - what it calls an "authoring error". The change to make pnglibconf.h - simply copies the file; in the future it may actually generate the - file from scripts/pnglibconf.dfa as the other build systems do. - Changed pngvalid to work when floating point APIs are disabled - Renamed the prebuilt scripts/pnglibconf.h to scripts/pnglibconf.h.prebuilt - Supply default values for PNG_USER_PRIVATEBUILD and PNG_USER_DLLFNAME_POSTFIX - in pngpriv.h in case the user neglected to define them in their pngusr.h - -Version 1.5.0beta46 [August 28, 2010] - Added new private header files to libpng_sources in CMakeLists.txt - Added PNG_READ_16BIT, PNG_WRITE_16BIT, and PNG_16BIT options. - Added reference to scripts/pnglibconf.h.prebuilt in the visualc71 project. - -Version 1.5.0beta47 [September 11, 2010] - Fixed a number of problems with 64-bit compilation reported by Visual - Studio 2010 (John Bowler). - -Version 1.5.0beta48 [October 4, 2010] - Updated CMakeLists.txt (Philip Lowman). - Revised autogen.sh to recognize and use $AUTOCONF, $AUTOMAKE, $AUTOHEADER, - $AUTOPOINT, $ACLOCAL and $LIBTOOLIZE - Fixed problem with symbols creation in Makefile.am which was assuming that - all versions of ccp write to standard output by default (Martin Banky). The - bug was introduced in libpng-1.2.9beta5. - Removed unused mkinstalldirs. - -Version 1.5.0beta49 [October 8, 2010] - Undid Makefile.am revision of 1.5.0beta48. - -Version 1.5.0beta50 [October 14, 2010] - Revised Makefile.in to account for mkinstalldirs being removed. - Added some "(unsigned long)" typecasts in printf statements in pngvalid.c. - Suppressed a compiler warning in png_handle_sPLT(). - Check for out-of-range text compression mode in png_set_text(). - -Version 1.5.0beta51 [October 15, 2010] - Changed embedded dates to "(PENDING RELEASE) in beta releases (and future - rc releases) to minimize the difference between releases. - -Version 1.5.0beta52 [October 16, 2010] - Restored some of the embedded dates (in png.h, png.c, documentation, etc.) - -Version 1.5.0beta53 [October 18, 2010] - Updated INSTALL to mention using "make maintainer-clean" and to remove - obsolete statement about a custom ltmain.sh - Disabled "color-tests" by default in Makefile.am so it will work with - automake versions earlier than 1.11.1 - Use document name "libpng-manual.txt" instead of "libpng-.txt" - to simplify version differences. - Removed obsolete remarks about setjmp handling from INSTALL. - Revised and renamed the typedef in png.h and png.c that was designed - to catch library and header mismatch. - -Version 1.5.0beta54 [November 10, 2010] - Require 48 bytes, not 64 bytes, for big_row_buf in overflow checks. - Used a consistent structure for the pngget.c functions. - -Version 1.5.0beta55 [November 21, 2010] - Revised png_get_uint_32, png_get_int_32, png_get_uint_16 (Cosmin) - Moved reading of file signature into png_read_sig (Cosmin) - Fixed atomicity of chunk header serialization (Cosmin) - Added test for io_state in pngtest.c (Cosmin) - Added "#!/bin/sh" at the top of contrib/pngminim/*/gather.sh scripts. - Changes to remove gcc warnings (John Bowler) - Certain optional gcc warning flags resulted in warnings in libpng code. - With these changes only -Wconversion and -Wcast-qual cannot be turned on. - Changes are trivial rearrangements of code. -Wconversion is not possible - for pngrutil.c (because of the widespread use of += et al on variables - smaller than (int) or (unsigned int)) and -Wcast-qual is not possible - with pngwio.c and pngwutil.c because the 'write' callback and zlib - compression both fail to declare their input buffers with 'const'. - -Version 1.5.0beta56 [December 7, 2010] - Added the private PNG_UNUSED() macro definition in pngpriv.h. - Added some commentary about PNG_EXPORT in png.h and pngconf.h - Revised PNG_EXPORT() macro and added PNG_EXPORTA() macro, with the - objective of simplifying and improving the cosmetic appearance of png.h. - Fixed some incorrect "=" macro names in pnglibconf.dfa - Included documentation of changes in 1.5.0 from 1.4.x in libpng-manual.txt - -Version 1.5.0beta57 [December 9, 2010] - Documented the pngvalid gamma error summary with additional comments and - print statements. - Improved missing symbol handling in checksym.awk; symbols missing in both - the old and new files can now be optionally ignored, treated as errors - or warnings. - Removed references to pngvcrd.c and pnggccrd.c from the vstudio project. - Updated "libpng14" to "libpng15" in the visualc71 project. - Enabled the strip16 tests in pngvalid.` - Don't display test results (except PASS/FAIL) when running "make test". - Instead put them in pngtest-log.txt - Added "--with-zprefix=" to configure.ac - Updated the prebuilt configuration files to autoconf version 2.68 - -Version 1.5.0beta58 [December 19, 2010] - Fixed interlace image handling and add test cases (John Bowler) - Fixed the clean rule in Makefile.am to remove pngtest-log.txt - Made minor changes to work around warnings in gcc 3.4 - -Version 1.5.0rc01 [December 27, 2010] - No changes. - -Version 1.5.0rc02 [December 27, 2010] - Eliminated references to the scripts/*.def files in project/visualc71. - -Version 1.5.0rc03 [December 28, 2010] - Eliminated scripts/*.def and revised Makefile.am accordingly - -Version 1.5.0rc04 [December 29, 2010] - Fixed bug in background transformation handling in pngrtran.c (it was - looking for the flag in png_ptr->transformations instead of in - png_ptr->flags) (David Raymond). - -Version 1.5.0rc05 [December 31, 2010] - Fixed typo in a comment in CMakeLists.txt (libpng14 => libpng15) (Cosmin) - -Version 1.5.0rc06 [January 4, 2011] - Changed the new configure option "zprefix=string" to "zlib-prefix=string" - -Version 1.5.0rc07 [January 4, 2011] - Updated copyright year. - -Version 1.5.0 [January 6, 2011] - No changes. - -version 1.5.1beta01 [January 8, 2011] - Added description of png_set_crc_action() to the manual. - Added a note in the manual that the type of the iCCP profile was changed - from png_charpp to png_bytepp in png_get_iCCP(). This change happened - in version 1.5.0beta36 but is not noted in the CHANGES. Similarly, - it was changed from png_charpp to png_const_bytepp in png_set_iCCP(). - Ensure that png_rgb_to_gray ignores palette mapped images, if libpng - internally happens to call it with one, and fixed a failure to handle - palette mapped images correctly. This fixes CVE-2690. - -Version 1.5.1beta02 [January 14, 2011] - Fixed a bug in handling of interlaced images (bero at arklinux.org). - Updated CMakeLists.txt (Clifford Yapp) - -Version 1.5.1beta03 [January 14, 2011] - Fixed typecasting of some png_debug() statements (Cosmin) - -Version 1.5.1beta04 [January 16, 2011] - Updated documentation of png_set|get_tRNS() (Thomas Klausner). - Mentioned in the documentation that applications must #include "zlib.h" - if they need access to anything in zlib.h, and that a number of - macros such as png_memset() are no longer accessible by applications. - Corrected pngvalid gamma test "sample" function to access all of the color - samples of each pixel, instead of sampling the red channel three times. - Prefixed variable names index, div, exp, gamma with "png_" to avoid "shadow" - warnings, and (mistakenly) changed png_exp() to exp(). - -Version 1.5.1beta05 [January 16, 2011] - Changed variable names png_index, png_div, png_exp, and png_gamma to - char_index, divisor, exp_b10, and gamma_val, respectively, and - changed exp() back to png_exp(). - -Version 1.5.1beta06 [January 20, 2011] - Prevent png_push_crc_skip() from hanging while reading an unknown chunk - or an over-large compressed zTXt chunk with the progressive reader. - Eliminated more GCC "shadow" warnings. - Revised png_fixed() in png.c to avoid compiler warning about reaching the - end without returning anything. - -Version 1.5.1beta07 [January 22, 2011] - In the manual, describe the png_get_IHDR() arguments in the correct order. - Added const_png_structp and const_png_infop types, and used them in - prototypes for most png_get_*() functions. - -Version 1.5.1beta08 [January 23, 2011] - Added png_get_io_chunk_type() and deprecated png_get_io_chunk_name() - Added synopses for the IO_STATE functions and other missing synopses - to the manual. Removed the synopses from libpngpf.3 because they - were out of date and no longer useful. Better information can be - obtained by reading the prototypes and comments in pngpriv.h - Attempted to fix cpp on Solaris with S. Studio 12 cc, fix build - Added a make macro DFNCPP that is a CPP that will accept the tokens in - a .dfn file and adds configure stuff to test for such a CPP. ./configure - should fail if one is not available. - Corrected const_png_ in png.h to png_const_ to avoid polluting the namespace. - Added png_get_current_row_number and png_get_current_pass_number for the - benefit of the user transform callback. - Added png_process_data_pause and png_process_data_skip for the benefit of - progressive readers that need to stop data processing or want to optimize - skipping of unread data (e.g., if the reader marks a chunk to be skipped.) - -Version 1.5.1beta09 [January 24, 2011] - Enhanced pngvalid, corrected an error in gray_to_rgb, corrected doc error. - pngvalid contains tests of transforms, which tests are currently disabled - because they are incompletely tested. gray_to_rgb was failing to expand - the bit depth for smaller bit depth images; this seems to be a long - standing error and resulted, apparently, in invalid output - (CVE-2011-0408, CERT VU#643140). The documentation did not accurately - describe what libpng really does when converting RGB to gray. - -Version 1.5.1beta10 [January 27, 2010] - Fixed incorrect examples of callback prototypes in the manual, that were - introduced in libpng-1.0.0. - In addition the order of the png_get_uint macros with respect to the - relevant function definitions has been reversed. This helps the - preprocessing of the symbol files be more robust. Furthermore, the - symbol file preprocessing now uses -DPNG_NO_USE_READ_MACROS even when - the library may actually be built with PNG_USE_READ_MACROS; this stops - the read macros interfering with the symbol file format. - Made the manual, synopses, and function prototypes use the function - argument names file_gamma, int_file_gamma, and srgb_intent consistently. - -Version 1.5.1beta11 [January 28, 2011] - Changed PNG_UNUSED from "param=param;" to "{if(param){}}". - Corrected local variable type in new API png_process_data_skip() - The type was self-evidently incorrect but only causes problems on 64-bit - architectures. - Added transform tests to pngvalid and simplified the arguments. - -Version 1.5.1rc01 [January 29, 2011] - No changes. - -Version 1.5.1rc02 [January 31, 2011] - Added a request in the manual that applications do not use "png_" or - "PNG_" to begin any of their own symbols. - Changed PNG_UNUSED to "(void)param;" and updated the commentary in pngpriv.h - -Version 1.5.1 [February 3, 2011] - No changes. - -Version 1.5.2beta01 [February 13, 2011] - More -Wshadow fixes for older gcc compilers. Older gcc versions apparently - check formal parameters names in function declarations (as well as - definitions) to see if they match a name in the global namespace. - Revised PNG_EXPORTA macro to not use an empty parameter, to accommodate the - old VisualC++ preprocessor. - Turned on interlace handling in png_read_png(). - Fixed gcc pendantic warnings. - Handle longjmp in Cygwin. - Fixed png_get_current_row_number() in the interlaced case. - Cleaned up ALPHA flags and transformations. - Implemented expansion to 16 bits. - -Version 1.5.2beta02 [February 19, 2011] - Fixed mistake in the descriptions of user read_transform and write_transform - function prototypes in the manual. The row_info struct is png_row_infop. - Reverted png_get_current_row_number() to previous (1.5.2beta01) behavior. - Corrected png_get_current_row_number documentation - Fixed the read/write row callback documentation. - This documents the current behavior, where the callback is called after - every row with information pertaining to the next row. - -Version 1.5.2beta03 [March 3, 2011] - Fixed scripts/makefile.vcwin32 - Updated contrib/pngsuite/README to add the word "modify". - Define PNG_ALLOCATED to blank when _MSC_VER<1300. - -Version 1.5.2rc01 [March 19, 2011] - Define remaining attributes to blank when MSC_VER<1300. - ifdef out mask arrays in pngread.c when interlacing is not supported. - -Version 1.5.2rc02 [March 22, 2011] - Added a hint to try CPP=/bin/cpp if "cpp -E" fails in scripts/pnglibconf.mak - and in contrib/pngminim/*/makefile, eg., on SunOS 5.10, and removed "strip" - from the makefiles. - Fixed a bug (present since libpng-1.0.7) that makes png_handle_sPLT() fail - to compile when PNG_NO_POINTER_INDEXING is defined (Chubanov Kirill) - -Version 1.5.2rc03 [March 24, 2011] - Don't include standard header files in png.h while building the symbol table, - to avoid cpp failure on SunOS (introduced PNG_BUILDING_SYMBOL_TABLE macro). - -Version 1.5.2 [March 31, 2011] - No changes. - -Version 1.5.3beta01 [April 1, 2011] - Re-initialize the zlib compressor before compressing non-IDAT chunks. - Added API functions (png_set_text_compression_level() and four others) to - set parameters for zlib compression of non-IDAT chunks. - -Version 1.5.3beta02 [April 3, 2011] - Updated scripts/symbols.def with new API functions. - Only compile the new zlib re-initializing code when text or iCCP is - supported, using PNG_WRITE_COMPRESSED_TEXT_SUPPORTED macro. - Improved the optimization of the zlib CMF byte (see libpng-1.2.6beta03). - Optimize the zlib CMF byte in non-IDAT compressed chunks - -Version 1.5.3beta03 [April 16, 2011] - Fixed gcc -ansi -pedantic compile. A strict ANSI system does not have - snprintf, and the "__STRICT_ANSI__" detects that condition more reliably - than __STDC__ (John Bowler). - Removed the PNG_PTR_NORETURN attribute because it too dangerous. It tells - the compiler that a user supplied callback (the error handler) does not - return, yet there is no guarantee in practice that the application code - will correctly implement the error handler because the compiler only - issues a warning if there is a mistake (John Bowler). - Removed the no-longer-used PNG_DEPSTRUCT macro. - Updated the zlib version to 1.2.5 in the VStudio project. - Fixed 64-bit builds where png_uint_32 is smaller than png_size_t in - pngwutil.c (John Bowler). - Fixed bug with stripping the filler or alpha channel when writing, that - was introduced in libpng-1.5.2beta01 (bug report by Andrew Church). - -Version 1.5.3beta04 [April 27, 2011] - Updated pngtest.png with the new zlib CMF optimization. - Cleaned up conditional compilation code and of background/gamma handling - Internal changes only except a new option to avoid compiling the - png_build_grayscale_palette API (which is not used at all internally.) - The main change is to move the transform tests (READ_TRANSFORMS, - WRITE_TRANSFORMS) up one level to the caller of the APIs. This avoids - calls to spurious functions if all transforms are disabled and slightly - simplifies those functions. Pngvalid modified to handle this. - A minor change is to stop the strip_16 and expand_16 interfaces from - disabling each other; this allows the future alpha premultiplication - code to use 16-bit intermediate values while still producing 8-bit output. - png_do_background and png_do_gamma have been simplified to take a single - pointer to the png_struct rather than pointers to every item required - from the png_struct. This makes no practical difference to the internal - code. - A serious bug in the pngvalid internal routine 'standard_display_init' has - been fixed - this failed to initialize the red channel and accidentally - initialized the alpha channel twice. - Changed png_struct jmp_buf member name from png_jmpbuf to tmp_jmpbuf to - avoid a possible clash with the png_jmpbuf macro on some platforms. - -Version 1.5.3beta05 [May 6, 2011] - Added the "_POSIX_SOURCE" feature test macro to ensure libpng sees the - correct API. _POSIX_SOURCE is defined in pngpriv.h, pngtest.c and - pngvalid.c to ensure that POSIX conformant systems disable non-POSIX APIs. - Removed png_snprintf and added formatted warning messages. This change adds - internal APIs to allow png_warning messages to have parameters without - requiring the host OS to implement snprintf. As a side effect the - dependency of the tIME-supporting RFC1132 code on stdio is removed and - PNG_NO_WARNINGS does actually work now. - Pass "" instead of '\0' to png_default_error() in png_err(). This mistake - was introduced in libpng-1.2.20beta01. This fixes CVE-2011-2691. - Added PNG_WRITE_OPTIMIZE_CMF_SUPPORTED macro to make the zlib "CMF" byte - optimization configureable. - IDAT compression failed if preceded by a compressed text chunk (bug - introduced in libpng-1.5.3beta01-02). This was because the attempt to - reset the zlib stream in png_write_IDAT happened after the first IDAT - chunk had been deflated - much too late. In this change internal - functions were added to claim/release the z_stream and, hopefully, make - the code more robust. Also deflateEnd checking is added - previously - libpng would ignore an error at the end of the stream. - -Version 1.5.3beta06 [May 8, 2011] - Removed the -D_ALL_SOURCE from definitions for AIX in CMakeLists.txt - Implemented premultiplied alpha support: png_set_alpha_mode API - -Version 1.5.3beta07 [May 11, 2011] - Added expand_16 support to the high level interface. - Added named value and 'flag' gamma support to png_set_gamma. Made a minor - change from the previous (unreleased) ABI/API to hide the exact value used - for Macs - it's not a good idea to embed this in the ABI! - Moved macro definitions for PNG_HAVE_IHDR, PNG_HAVE_PLTE, and PNG_AFTER_IDAT - from pngpriv.h to png.h because they must be visible to applications - that call png_set_unknown_chunks(). - Check for up->location !PNG_AFTER_IDAT when writing unknown chunks - before IDAT. - -Version 1.5.3beta08 [May 16, 2011] - Improved "pngvalid --speed" to exclude more of pngvalid from the time. - Documented png_set_alpha_mode(), other changes in libpng.3/libpng-manual.txt - The cHRM chunk now sets the defaults for png_set_rgb_to_gray() (when negative - parameters are supplied by the caller), while in the absence of cHRM - sRGB/Rec 709 values are still used. This introduced a divide-by-zero - bug in png_handle_cHRM(). - The bKGD chunk no longer overwrites the background value set by - png_set_background(), allowing the latter to be used before the file - header is read. It never performed any useful function to override - the default anyway. - Added memory overwrite and palette image checks to pngvalid.c - Previously palette image code was poorly checked. Since the transformation - code has a special palette path in most cases this was a severe weakness. - Minor cleanup and some extra checking in pngrutil.c and pngrtran.c. When - expanding an indexed image, always expand to RGBA if transparency is - present. - -Version 1.5.3beta09 [May 17, 2011] - Reversed earlier 1.5.3 change of transformation order; move png_expand_16 - back where it was. The change doesn't work because it requires 16-bit - gamma tables when the code only generates 8-bit ones. This fails - silently; the libpng code just doesn't do any gamma correction. Moving - the tests back leaves the old, inaccurate, 8-bit gamma calculations, but - these are clearly better than none! - -Version 1.5.3beta10 [May 20, 2011] - - png_set_background() and png_expand_16() did not work together correctly. - This problem is present in 1.5.2; if png_set_background is called with - need_expand false and the matching 16 bit color libpng erroneously just - treats it as an 8-bit color because of where png_do_expand_16 is in the - transform list. This simple fix reduces the supplied colour to 8-bits, - so it gets smashed, but this is better than the current behavior. - Added tests for expand16, more fixes for palette image tests to pngvalid. - Corrects the code for palette image tests and disables attempts to - validate palette colors. - -Version 1.5.3rc01 [June 3, 2011] - No changes. - -Version 1.5.3rc02 [June 8, 2011] - Fixed uninitialized memory read in png_format_buffer() (Bug report by - Frank Busse, CVE-2011-2501, related to CVE-2004-0421). - -Version 1.5.3beta11 [June 11, 2011] - Fixed png_handle_sCAL which is broken in 1.5. This fixes CVE 2011-2692. - Added sCAL to pngtest.png - Revised documentation about png_set_user_limits() to say that it also affects - png writing. - Revised handling of png_set_user_limits() so that it can increase the - limit beyond the PNG_USER_WIDTH|HEIGHT_MAX; previously it could only - reduce it. - Make the 16-to-8 scaling accurate. Dividing by 256 with no rounding is - wrong (high by one) 25% of the time. Dividing by 257 with rounding is - wrong in 128 out of 65536 cases. Getting the right answer all the time - without division is easy. - Added "_SUPPORTED" to the PNG_WRITE_CUSTOMIZE_ZTXT_COMPRESSION macro. - Added projects/owatcom, an IDE project for OpenWatcom to replace - scripts/makefile.watcom. This project works with OpenWatcom 1.9. The - IDE autogenerates appropriate makefiles (libpng.mk) for batch processing. - The project is configurable, unlike the Visual Studio project, so long - as the developer has an awk. - Changed png_set_gAMA to limit the gamma value range so that the inverse - of the stored value cannot overflow the fixed point representation, - and changed other things OpenWatcom warns about. - Revised pngvalid.c to test PNG_ALPHA_MODE_SUPPORTED correctly. This allows - pngvalid to build when ALPHA_MODE is not supported, which is required if - it is to build on libpng 1.4. - Removed string/memory macros that are no longer used and are not - necessarily fully supportable, particularly png_strncpy and png_snprintf. - Added log option to pngvalid.c and attempted to improve gamma messages. - -Version 1.5.3 [omitted] - People found the presence of a beta release following an rc release - to be confusing; therefore we bump the version to libpng-1.5.4beta01 - and there will be no libpng-1.5.3 release. - -Version 1.5.4beta01 [June 14, 2011] - Made it possible to undefine PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED - to get the same (inaccurate) output as libpng-1.5.2 and earlier. - Moved definitions of PNG_HAVE_IHDR, PNG_AFTER_IDAT, and PNG_HAVE_PLTE - outside of an unknown-chunk block in png.h because they are also - needed for other uses. - -Version 1.5.4beta02 [June 14, 2011] - Fixed and clarified LEGACY 16-to-8 scaling code. - Added png_set_chop_16() API, to match inaccurate results from previous - libpng versions. - Removed the ACCURATE and LEGACY options (they are no longer useable) - Use the old scaling method for background if png_set_chop_16() was - called. - Made png_set_chop_16() API removeable by disabling PNG_CHOP_16_TO_8_SUPPORTED - -Version 1.5.4beta03 [June 15, 2011] - Fixed a problem in png_do_expand_palette() exposed by optimization in - 1.5.3beta06 - Also removed a spurious and confusing "trans" member ("trans") from png_info. - The palette expand optimization prevented expansion to an intermediate RGBA - form if tRNS was present but alpha was marked to be stripped; this exposed - a check for tRNS in png_do_expand_palette() which is inconsistent with the - code elsewhere in libpng. - Correction to the expand_16 code; removed extra instance of - png_set_scale_16_to_8 from pngpriv.h - -Version 1.5.4beta04 [June 16, 2011] - Added a missing "#ifdef PNG_READ_BACKGROUND_SUPPORTED/#endif" in pngrtran.c - Added PNG_TRANSFORM_CHOP_16 to the high-level read transforms. - Made PNG_READ_16_TO_8_ACCURATE_SCALE configurable again. If this is - not enabled, png_set_strip_16() and png_do_scale_16_to_8() aren't built. - Revised contrib/visupng, gregbook, and pngminim to demonstrate chop_16_to_8 - -Version 1.5.4beta05 [June 16, 2011] - Renamed png_set_strip_16() to png_set_scale_16() and renamed - png_set_chop_16() to png_set_strip(16) in an attempt to minimize the - behavior changes between libpng14 and libpng15. - -Version 1.5.4beta06 [June 18, 2011] - Fixed new bug that was causing both strip_16 and scale_16 to be applied. - -Version 1.5.4beta07 [June 19, 2011] - Fixed pngvalid, simplified macros, added checking for 0 in sCAL. - The ACCURATE scale macro is no longer defined in 1.5 - call the - png_scale_16_to_8 API. Made sure that PNG_READ_16_TO_8 is still defined - if the png_strip_16_to_8 API is present. png_check_fp_number now - maintains some state so that positive, negative and zero values are - identified. sCAL uses these to be strictly spec conformant. - -Version 1.5.4beta08 [June 23, 2011] - Fixed pngvalid if ACCURATE_SCALE is defined. - Updated scripts/pnglibconf.h.prebuilt. - -Version 1.5.4rc01 [June 30, 2011] - Define PNG_ALLOCATED to "restrict" only if MSC_VER >= 1400. - -Version 1.5.4 [July 7, 2011] - No changes. - -Version 1.5.5beta01 [July 13, 2011] - Fixed some typos and made other minor changes in the manual. - Updated contrib/pngminus/makefile.std (Samuli Souminen) - -Version 1.5.5beta02 [July 14, 2011] - Revised Makefile.am and Makefile.in to look in the right directory for - pnglibconf.h.prebuilt - -Version 1.5.5beta03 [July 27, 2011] - Enabled compilation with g++ compiler. This compiler does not recognize - the file extension, so it always compiles with C++ rules. Made minor - changes to pngrutil.c to cast results where C++ expects it but C does not. - Minor editing of libpng.3 and libpng-manual.txt. - -Version 1.5.5beta04 [July 29, 2011] - Revised CMakeLists.txt (Clifford Yapp) - Updated commentary about the png_rgb_to_gray() default coefficients - in the manual and in pngrtran.c - -Version 1.5.5beta05 [August 17, 2011] - Prevent unexpected API exports from non-libpng DLLs on Windows. The "_DLL" - is removed from the test of whether a DLL is being built (this erroneously - caused the libpng APIs to be marked as DLL exports in static builds under - Microsoft Visual Studio). Almost all of the libpng building configuration - is moved from pngconf.h to pngpriv.h, but PNG_DLL_EXPORT remains in - pngconf.h, though, so that it is colocated with the import definition (it - is no longer used anywhere in the installed headers). The VStudio project - definitions have been cleaned up: "_USRDLL" has been removed from the - static library builds (this was incorrect), and PNG_USE_DLL has been added - to pngvalid to test the functionality (pngtest does not supply it, - deliberately). The spurious "_EXPORTS" has been removed from the - libpng build (all these errors were a result of copy/paste between project - configurations.) - Added new types and internal functions for CIE RGB end point handling to - pngpriv.h (functions yet to be implemented). - -Version 1.5.5beta06 [August 26, 2011] - Ensure the CMAKE_LIBRARY_OUTPUT_DIRECTORY is set in CMakeLists.txt - (Clifford Yap) - Fixes to rgb_to_gray and cHRM XYZ APIs (John Bowler): - The rgb_to_gray code had errors when combined with gamma correction. - Some pixels were treated as true grey when they weren't and such pixels - and true grey ones were not gamma corrected (the original value of the - red component was used instead). APIs to get and set cHRM using color - space end points have been added and the rgb_to_gray code that defaults - based on cHRM, and the divide-by-zero bug in png_handle_cHRM (CERT - VU#477046, CVE-2011-3328, introduced in 1.5.4) have been corrected. - A considerable number of tests has been added to pngvalid for the - rgb_to_gray transform. - Arithmetic errors in rgb_to_gray whereby the calculated gray value was - truncated to the bit depth rather than rounded have been fixed except in - the 8-bit non-gamma-corrected case (where consistency seems more important - than correctness.) The code still has considerable inaccuracies in the - 8-bit case because 8-bit linear arithmetic is used. - -Version 1.5.5beta07 [September 7, 2011] - Added "$(ARCH)" option to makefile.darwin - Added SunOS support to configure.ac and Makefile.am - Changed png_chunk_benign_error() to png_warning() in png.c, in - png_XYZ_from_xy_checked(). - -Version 1.5.5beta08 [September 10, 2011] - Fixed 64-bit compilation errors (gcc). The errors fixed relate - to conditions where types that are 32 bits in the GCC 32-bit - world (uLong and png_size_t) become 64 bits in the 64-bit - world. This produces potential truncation errors which the - compiler correctly flags. - Relocated new HAVE_SOLARIS_LD definition in configure.ac - Constant changes for 64-bit compatibility (removal of L suffixes). The - 16-bit cases still use "L" as we don't have a 16-bit test system. - -Version 1.5.5rc01 [September 15, 2011] - Removed "L" suffixes in pngpriv.h - -Version 1.5.5 [September 22, 2011] - No changes. - -Version 1.5.6beta01 [September 22, 2011] - Fixed some 64-bit type conversion warnings in pngrtran.c - Moved row_info from png_struct to a local variable. - The various interlace mask arrays have been made into arrays of - bytes and made PNG_CONST and static (previously some arrays were - marked PNG_CONST and some weren't). - Additional checks have been added to the transform code to validate the - pixel depths after the transforms on both read and write. - Removed some redundant code from pngwrite.c, in png_destroy_write_struct(). - Changed chunk reading/writing code to use png_uint_32 instead of png_byte[4]. - This removes the need to allocate temporary strings for chunk names on - the stack in the read/write code. Unknown chunk handling still uses the - string form because this is exposed in the API. - -Version 1.5.6beta02 [September 26, 2011] - Added a note in the manual the png_read_update_info() must be called only - once with a particular info_ptr. - Fixed a typo in the definition of the new PNG_STRING_FROM_CHUNK(s,c) macro. - -Version 1.5.6beta03 [September 28, 2011] - Revised test-pngtest.sh to report FAIL when pngtest fails. - Added "--strict" option to pngtest, to report FAIL when the failure is - only because the resulting valid files are different. - Revised CMakeLists.txt to work with mingw and removed some material from - CMakeLists.txt that is no longer useful in libpng-1.5. - -Version 1.5.6beta04 [October 5, 2011] - Fixed typo in Makefile.in and Makefile.am ("-M Wl" should be "-M -Wl")." - -Version 1.5.6beta05 [October 12, 2011] - Speed up png_combine_row() for interlaced images. This reduces the generality - of the code, allowing it to be optimized for Adam7 interlace. The masks - passed to png_combine_row() are now generated internally, avoiding - some code duplication and localizing the interlace handling somewhat. - Align png_struct::row_buf - previously it was always unaligned, caused by - a bug in the code that attempted to align it; the code needs to subtract - one from the pointer to take account of the filter byte prepended to - each row. - Optimized png_combine_row() when rows are aligned. This gains a small - percentage for 16-bit and 32-bit pixels in the typical case where the - output row buffers are appropriately aligned. The optimization was not - previously possible because the png_struct buffer was always misaligned. - Fixed bug in png_write_chunk_header() debug print, introduced in 1.5.6beta01. - -Version 1.5.6beta06 [October 17, 2011] - Removed two redundant tests for unitialized row. - Fixed a relatively harmless memory overwrite in compressed text writing - with a 1 byte zlib buffer. - Add ability to call png_read_update_info multiple times to pngvalid.c. - Fixes for multiple calls to png_read_update_info. These fixes attend to - most of the errors revealed in pngvalid, however doing the gamma work - twice results in inaccuracies that can't be easily fixed. There is now - a warning in the code if this is going to happen. - Turned on multiple png_read_update_info in pngvalid transform tests. - Prevent libpng from overwriting unused bits at the end of the image when - it is not byte aligned, while reading. Prior to libpng-1.5.6 libpng would - overwrite the partial byte at the end of each row if the row width was not - an exact multiple of 8 bits and the image is not interlaced. - -Version 1.5.6beta07 [October 21, 2011] - Made png_ptr->prev_row an aligned pointer into png_ptr->big_prev_row - (Mans Rullgard). - -Version 1.5.6rc01 [October 26, 2011] - Changed misleading "Missing PLTE before cHRM" warning to "Out of place cHRM" - -Version 1.5.6rc02 [October 27, 2011] - Added LSR() macro to defend against buggy compilers that evaluate non-taken - code branches and complain about out-of-range shifts. - -Version 1.5.6rc03 [October 28, 2011] - Renamed the LSR() macro to PNG_LSR() and added PNG_LSL() macro. - Fixed compiler warnings with Intel and MSYS compilers. The logical shift - fix for Microsoft Visual C is required by other compilers, so this - enables that fix for all compilers when using compile-time constants. - Under MSYS 'byte' is a name declared in a system header file, so we - changed the name of a local variable to avoid the warnings that result. - Added #define PNG_ALIGN_TYPE PNG_ALIGN_NONE to contrib/pngminim/*/pngusr.h - -Version 1.5.6 [November 3, 2011] - No changes. - -Version 1.5.7beta01 [November 4, 2011] - Added support for ARM processor, when decoding all PNG up-filtered rows - and any other-filtered rows with 3 or 4 bytes per pixel (Mans Rullgard). - Fixed bug in pngvalid on early allocation failure; fixed type cast in - pngmem.c; pngvalid would attempt to call png_error() if the allocation - of a png_struct or png_info failed. This would probably have led to a - crash. The pngmem.c implementation of png_malloc() included a cast - to png_size_t which would fail on large allocations on 16-bit systems. - Fix for the preprocessor of the Intel C compiler. The preprocessor - splits adjacent @ signs with a space; this changes the concatentation - token from @-@-@ to PNG_JOIN; that should work with all compiler - preprocessors. - Paeth filter speed improvements from work by Siarhei Siamashka. This - changes the 'Paeth' reconstruction function to improve the GCC code - generation on x86. The changes are only part of the suggested ones; - just the changes that definitely improve speed and remain simple. - The changes also slightly increase the clarity of the code. - -Version 1.5.7beta02 [November 11, 2011] - Check compression_type parameter in png_get_iCCP and remove spurious - casts. The compression_type parameter is always assigned to, so must - be non-NULL. The cast of the profile length potentially truncated the - value unnecessarily on a 16-bit int system, so the cast of the (byte) - compression type to (int) is specified by ANSI-C anyway. - Fixed FP division by zero in pngvalid.c; the 'test_pixel' code left - the sBIT fields in the test pixel as 0, which resulted in a floating - point division by zero which was irrelevant but causes systems where - FP exceptions cause a crash. Added code to pngvalid to turn on FP - exceptions if the appropriate glibc support is there to ensure this is - tested in the future. - Updated scripts/pnglibconf.mak and scripts/makefile.std to handle the - new PNG_JOIN macro. - Added versioning to pnglibconf.h comments. - Simplified read/write API initial version; basic read/write tested on - a variety of images, limited documentation (in the header file.) - Installed more accurate linear to sRGB conversion tables. The slightly - modified tables reduce the number of 16-bit values that - convert to an off-by-one 8-bit value. The "makesRGB.c" code that was used - to generate the tables is now in a contrib/sRGBtables sub-directory. - -Version 1.5.7beta03 [November 17, 2011] - Removed PNG_CONST from the sRGB table declarations in pngpriv.h and png.c - Added run-time detection of NEON support. - Added contrib/libtests; includes simplified API test and timing test and - a color conversion utility for rapid checking of failed 'pngstest' results. - Multiple transform bug fixes plus a work-round for double gamma correction. - libpng does not support more than one transform that requires linear data - at once - if this is tried typically the results is double gamma - correction. Since the simplified APIs can need rgb to gray combined with - a compose operation it is necessary to do one of these outside the main - libpng transform code. This check-in also contains fixes to various bugs - in the simplified APIs themselves and to some bugs in compose and rgb to - gray (on palette) itself. - Fixes for C++ compilation using g++ When libpng source is compiled - using g++. The compiler imposes C++ rules on the C source; thus it - is desireable to make the source work with either C or C++ rules - without throwing away useful error information. This change adds - png_voidcast to allow C semantic (void*) cases or the corresponding - C++ static_cast operation, as appropriate. - Added --noexecstack to assembler file compilation. GCC does not set - this on assembler compilation, even though it does on C compilation. - This creates security issues if assembler code is enabled; the - work-around is to set it by default in the flags for $(CCAS) - Work around compilers that don't support declaration of const data. Some - compilers fault 'extern const' data declarations (because the data is - not initialized); this turns on const-ness only for compilers where - this is known to work. - -Version 1.5.7beta04 [November 17, 2011] - Since the gcc driver does not recognize the --noexecstack flag, we must - use the -Wa prefix to have it passed through to the assembler. - Also removed a duplicate setting of this flag. - Added files that were omitted from the libpng-1.5.7beta03 zip distribution. - -Version 1.5.7beta05 [November 25, 2011] - Removed "zTXt" from warning in generic chunk decompression function. - Validate time settings passed to png_set_tIME() and png_convert_to_rfc1123() - (Frank Busse). Note: This prevented CVE-2015-7981 from affecting - libpng-1.5.7 and later. - Added MINGW support to CMakeLists.txt - Reject invalid compression flag or method when reading the iTXt chunk. - Backed out 'simplified' API changes. The API seems too complex and there - is a lack of consensus or enthusiasm for the proposals. The API also - reveals significant bugs inside libpng (double gamma correction and the - known bug of being unable to retrieve a corrected palette). It seems - better to wait until the bugs, at least, are corrected. - Moved pngvalid.c into contrib/libtests - Rebuilt Makefile.in, configure, etc., with autoconf-2.68 - -Version 1.5.7rc01 [December 1, 2011] - Replaced an "#if" with "#ifdef" in pngrtran.c - Revised #if PNG_DO_BC block in png.c (use #ifdef and add #else) - -Version 1.5.7rc02 [December 5, 2011] - Revised project files and contrib/pngvalid/pngvalid.c to account for - the relocation of pngvalid into contrib/libtests. - Revised pngconf.h to use " __declspec(restrict)" only when MSC_VER >= 1400, - as in libpng-1.5.4. - Put CRLF line endings in the owatcom project files. - -Version 1.5.7rc03 [December 7, 2011] - Updated CMakeLists.txt to account for the relocation of pngvalid.c - -Version 1.5.7 [December 15, 2011] - Minor fixes to pngvalid.c for gcc 4.6.2 compatibility to remove warnings - reported by earlier versions. - Fixed minor memset/sizeof errors in pngvalid.c. - -Version 1.6.0beta01 [December 15, 2011] - Removed machine-generated configure files from the GIT repository (they will - continue to appear in the tarball distributions and in the libpng15 and - earlier GIT branches). - Restored the new 'simplified' API, which was started in libpng-1.5.7beta02 - but later deleted from libpng-1.5.7beta05. - Added example programs for the new 'simplified' API. - Added ANSI-C (C90) headers and require them, and take advantage of the - change. Also fixed some of the projects/* and contrib/* files that needed - updates for libpng16 and the move of pngvalid.c. - With this change the required ANSI-C header files are assumed to exist: the - implementation must provide float.h, limits.h, stdarg.h and stddef.h and - libpng relies on limits.h and stddef.h existing and behaving as defined - (the other two required headers aren't used). Non-ANSI systems that don't - have stddef.h or limits.h will have to provide an appropriate fake - containing the relevant types and #defines. - Dropped support for 16-bit platforms. The use of FAR/far 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. Libpng 1.6 may - not currently work on such systems -- it seems likely that it will - ask 'malloc' for more than 65535 bytes with any image that has a - sufficiently large row size (rather than simply failing to read such - images). - New tools directory containing tools used to generate libpng code. - Fixed race conditions in parallel make builds. With higher degrees of - parallelism during 'make' the use of the same temporary file names such - as 'dfn*' can result in a race where a temporary file from one arm of the - build is deleted or overwritten in another arm. This changes the - temporary files for suffix rules to always use $* and ensures that the - non-suffix rules use unique file names. - -Version 1.6.0beta02 [December 21, 2011] - Correct configure builds where build and source directories are separate. - The include path of 'config.h' was erroneously made relative in pngvalid.c - in libpng 1.5.7. - -Version 1.6.0beta03 [December 22, 2011] - Start-up code size improvements, error handler flexibility. These changes - alter how the tricky allocation of the initial png_struct and png_info - structures are handled. png_info is now handled in pretty much the same - way as everything else, except that the allocations handle NULL return - silently. png_struct is changed in a similar way on allocation and on - deallocation a 'safety' error handler is put in place (which should never - be required). The error handler itself is changed to permit mismatches - in the application and libpng error buffer size; however, this means a - silent change to the API to return the jmp_buf if the size doesn't match - the size from the libpng compilation; libpng now allocates the memory and - this may fail. Overall these changes result in slight code size - reductions; however, this is a reduction in code that is always executed - so is particularly valuable. Overall on a 64-bit system the libpng DLL - decreases in code size by 1733 bytes. pngerror.o increases in size by - about 465 bytes because of the new functionality. - Added png_convert_to_rfc1123_buffer() and deprecated png_convert_to_rfc1123() - to avoid including a spurious buffer in the png_struct. - -Version 1.6.0beta04 [December 30, 2011] - Regenerated configure scripts with automake-1.11.2 - Eliminated png_info_destroy(). It is now used only in png.c and only calls - one other internal function and memset(). - Enabled png_get_sCAL_fixed() if floating point APIs are enabled. Previously - it was disabled whenever internal fixed point arithmetic was selected, - which meant it didn't exist even on systems where FP was available but not - preferred. - Added pngvalid.c compile time checks for const APIs. - Implemented 'restrict' for png_info and png_struct. Because of the way - libpng works both png_info and png_struct are always accessed via a - single pointer. This means adding C99 'restrict' to the pointer gives - the compiler some opportunity to optimize the code. This change allows - that. - Moved AC_MSG_CHECKING([if libraries can be versioned]) later to the proper - location in configure.ac (Gilles Espinasse). - Changed png_memcpy to C assignment where appropriate. Changed all those - uses of png_memcpy that were doing a simple assignment to assignments - (all those cases where the thing being copied is a non-array C L-value). - Added some error checking to png_set_*() routines. - Removed the reference to the non-exported function png_memcpy() from - example.c. - Fixed the Visual C 64-bit build - it requires jmp_buf to be aligned, but - it had become misaligned. - Revised contrib/pngminus/pnm2png.c to avoid warnings when png_uint_32 - and unsigned long are of different sizes. - -Version 1.6.0beta05 [January 15, 2012] - Updated manual with description of the simplified API (copied from png.h) - Fix bug in pngerror.c: some long warnings were being improperly truncated - (CVE-2011-3464, bug introduced in libpng-1.5.3beta05). - -Version 1.6.0beta06 [January 24, 2012] - Added palette support to the simplified APIs. This commit - changes some of the macro definitions in png.h, app code - may need corresponding changes. - Increased the formatted warning buffer to 192 bytes. - Added color-map support to simplified API. This is an initial version for - review; the documentation has not yet been updated. - Fixed Min/GW uninstall to remove libpng.dll.a - -Version 1.6.0beta07 [January 28, 2012] - Eliminated Intel icc/icl compiler warnings. The Intel (GCC derived) - compiler issues slightly different warnings from those issued by the - current vesions of GCC. This eliminates those warnings by - adding/removing casts and small code rewrites. - Updated configure.ac from autoupdate: added --enable-werror option. - Also some layout regularization and removal of introduced tab characters - (replaced with 3-character indentation). Obsolete macros identified by - autoupdate have been removed; the replacements are all in 2.59 so - the pre-req hasn't been changed. --enable-werror checks for support - for -Werror (or the given argument) in the compiler. This mimics the - gcc configure option by allowing -Werror to be turned on safely; without - the option the tests written in configure itself fail compilation because - they cause compiler warnings. - Rewrote autogen.sh to run autoreconf instead of running tools one-by-one. - Conditionalize the install rules for MINGW and CYGWIN in CMakeLists.txt and - set CMAKE_LIBRARY_OUTPUT_DIRECTORY to "lib" on all platforms (C. Yapp). - Freeze libtool files in the 'scripts' directory. This version of autogen.sh - attempts to dissuade people from running it when it is not, or should not, - be necessary. In fact, autogen.sh does not work when run in a libpng - directory extracted from a tar distribution anymore. You must run it in - a GIT clone instead. - Added two images to contrib/pngsuite (1-bit and 2-bit transparent grayscale), - and renamed three whose names were inconsistent with those in - pngsuite/README.txt. - -Version 1.6.0beta08 [February 1, 2012] - Fixed Image::colormap misalignment in pngstest.c - Check libtool/libtoolize version number (2.4.2) in configure.ac - Divide test-pngstest.sh into separate pngstest runs for basic and - transparent images. - Moved automake options to AM_INIT_AUTOMAKE in configure.ac - Added color-tests, silent-rules (Not yet implemented in Makefile.am) and - version checking to configure.ac - Improved pngstest speed by not doing redundant tests and add const to - the background parameter of png_image_finish_read. The --background - option is now done automagically only when required, so that commandline - option no longer exists. - Cleaned up pngpriv.h to consistently declare all functions and data. - Also eliminated PNG_CONST_DATA, which is apparently not needed but we - can't be sure until it is gone. - Added symbol prefixing that allows all the libpng external symbols - to be prefixed (suggested by Reuben Hawkins). - Updated "ftbb*.png" list in the owatcom and vstudio projects. - Fixed 'prefix' builds on clean systems. The generation of pngprefix.h - should not require itself. - Updated INSTALL to explain that autogen.sh must be run in a GIT clone, - not in a libpng directory extracted from a tar distribution. - -Version 1.6.0beta09 [February 1, 2012] - Reverted the prebuilt configure files to libpng-1.6.0beta05 condition. - -Version 1.6.0beta10 [February 3, 2012] - Added Z_SOLO for zlib-1.2.6+ and correct pngstest tests - Updated list of test images in CMakeLists.txt - Updated the prebuilt configure files to current condition. - Revised INSTALL information about autogen.sh; it works in tar distributions. - -Version 1.6.0beta11 [February 16, 2012] - Fix character count in pngstest command in projects/owatcom/pngstest.tgt - Revised test-pngstest.sh to report PASS/FAIL for each image. - Updated documentation about the simplified API. - Corrected estimate of error in libpng png_set_rgb_to_gray API. The API is - extremely inaccurate for sRGB conversions because it uses an 8-bit - intermediate linear value and it does not use the sRGB transform, so it - suffers from the known instability in gamma transforms for values close - to 0 (see Poynton). The net result is that the calculation has a maximum - error of 14.99/255; 0.5/255^(1/2.2). pngstest now uses 15 for the - permitted 8-bit error. This may still not be enough because of arithmetic - error. - Removed some unused arrays (with #ifdef) from png_read_push_finish_row(). - Fixed a memory overwrite bug in simplified read of RGB PNG with - non-linear gamma Also bugs in the error checking in pngread.c and changed - quite a lot of the checks in pngstest.c to be correct; either correctly - written or not over-optimistic. The pngstest changes are insufficient to - allow all possible RGB transforms to be passed; pngstest cmppixel needs - to be rewritten to make it clearer which errors it allows and then changed - to permit known inaccuracies. - Removed tests for no-longer-used *_EMPTY_PLTE_SUPPORTED from pngstruct.h - Fixed fixed/float API export conditionals. 1) If FIXED_POINT or - FLOATING_POINT options were switched off, png.h ended up with lone ';' - characters. This is not valid ANSI-C outside a function. The ';' - characters have been moved inside the definition of PNG_FP_EXPORT and - PNG_FIXED_EXPORT. 2) If either option was switched off, the declaration - of the corresponding functions were completely omitted, even though some - of them are still used internally. The result is still valid, but - produces warnings from gcc with some warning options (including -Wall). The - fix is to cause png.h to declare the functions with PNG_INTERNAL_FUNCTION - when png.h is included from pngpriv.h. - Check for invalid palette index while reading paletted PNG. When one is - found, issue a warning and increase png_ptr->num_palette accordingly. - Apps are responsible for checking to see if that happened. - -Version 1.6.0beta12 [February 18, 2012] - Do not increase num_palette on invalid_index. - Relocated check for invalid palette index to pngrtran.c, after unpacking - the sub-8-bit pixels. - Fixed CVE-2011-3026 buffer overrun bug. This bug was introduced when - iCCP chunk support was added at libpng-1.0.6. Deal more correctly with the - test on iCCP chunk length. Also removed spurious casts that may hide - problems on 16-bit systems. - -Version 1.6.0beta13 [February 24, 2012] - Eliminated redundant png_push_read_tEXt|zTXt|iTXt|unknown code from - pngpread.c and use the sequential png_handle_tEXt, etc., in pngrutil.c; - now that png_ptr->buffer is inaccessible to applications, the special - handling is no longer useful. - Added PNG_SAFE_LIMITS feature to pnglibconf.dfa, pngpriv.h, and new - pngusr.dfa to reset the user limits to safe ones if PNG_SAFE_LIMITS is - defined. To enable, use "CPPFLAGS=-DPNG_SAFE_LIMITS_SUPPORTED=1" on the - configure command or put #define PNG_SAFE_LIMITS_SUPPORTED in - pnglibconf.h.prebuilt and pnglibconf.h. - -Version 1.6.0beta14 [February 27, 2012] - Added information about the new limits in the manual. - Updated Makefile.in - -Version 1.6.0beta15 [March 2, 2012] - Removed unused "current_text" members of png_struct and the png_free() - of png_ptr->current_text from pngread.c - Rewrote pngstest.c for substantial speed improvement. - Fixed transparent pixel and 16-bit rgb tests in pngstest and removed a - spurious check in pngwrite.c - Added PNG_IMAGE_FLAG_FAST for the benefit of applications that store - intermediate files, or intermediate in-memory data, while processing - image data with the simplified API. The option makes the files larger - but faster to write and read. pngstest now uses this by default; this - can be disabled with the --slow option. - Improved pngstest fine tuning of error numbers, new test file generator. - The generator generates images that test the full range of sample values, - allow the error numbers in pngstest to be tuned and checked. makepng - also allows generation of images with extra chunks, although this is - still work-in-progress. - Added check for invalid palette index while reading. - Fixed some bugs in ICC profile writing. The code should now accept - all potentially valid ICC profiles and reject obviously invalid ones. - It now uses png_error() to do so rather than casually writing a PNG - without the necessary color data. - Removed whitespace from the end of lines in all source files and scripts. - -Version 1.6.0beta16 [March 6, 2012] - Relocated palette-index checking function from pngrutil.c to pngtrans.c - Added palette-index checking while writing. - Changed png_inflate() and calling routines to avoid overflow problems. - This is an intermediate check-in that solves the immediate problems and - introduces one performance improvement (avoiding a copy via png_ptr->zbuf.) - Further changes will be made to make ICC profile handling more secure. - Fixed build warnings (MSVC, GCC, GCC v3). Cygwin GCC with default options - declares 'index' as a global, causing a warning if it is used as a local - variable. GCC 64-bit warns about assigning a (size_t) (unsigned 64-bit) - to an (int) (signed 32-bit). MSVC, however, warns about using the - unary '-' operator on an unsigned value (even though it is well defined - by ANSI-C to be ~x+1). The padding calculation was changed to use a - different method. Removed the tests on png_ptr->pass. - Added contrib/libtests/tarith.c to test internal arithmetic functions from - png.c. This is a libpng maintainer program used to validate changes to the - internal arithmetic functions. - Made read 'inflate' handling like write 'deflate' handling. The read - code now claims and releases png_ptr->zstream, like the write code. - The bug whereby the progressive reader failed to release the zstream - is now fixed, all initialization is delayed, and the code checks for - changed parameters on deflate rather than always calling - deflatedEnd/deflateInit. - Validate the zTXt strings in pngvalid. - Added code to validate the windowBits value passed to deflateInit2(). - If the call to deflateInit2() is wrong a png_warning will be issued - (in fact this is harmless, but the PNG data produced may be sub-optimal). - -Version 1.6.0beta17 [March 10, 2012] - Fixed PNG_LIBPNG_BUILD_BASE_TYPE definition. - Reject all iCCP chunks after the first, even if the first one is invalid. - Deflate/inflate was reworked to move common zlib calls into single - functions [rw]util.c. A new shared keyword check routine was also added - and the 'zbuf' is no longer allocated on progressive read. It is now - possible to call png_inflate() incrementally. A warning is no longer - issued if the language tag or translated keyword in the iTXt chunk - has zero length. - If benign errors are disabled use maximum window on ancilliary inflate. - This works round a bug introduced in 1.5.4 where compressed ancillary - chunks could end up with a too-small windowBits value in the deflate - header. - -Version 1.6.0beta18 [March 16, 2012] - Issue a png_benign_error() instead of png_warning() about bad palette index. - In pngtest, treat benign errors as errors if "-strict" is present. - Fixed an off-by-one error in the palette index checking function. - Fixed a compiler warning under Cygwin (Windows-7, 32-bit system) - Revised example.c to put text strings in a temporary character array - instead of directly assigning string constants to png_textp members. - This avoids compiler warnings when -Wwrite-strings is enabled. - Added output flushing to aid debugging under Visual Studio. Unfortunately - this is necessary because the VS2010 output window otherwise simply loses - the error messages on error (they weren't flushed to the window before - the process exited, apparently!) - Added configuration support for benign errors and changed the read - default. Also changed some warnings in the iCCP and sRGB handling - from to benign errors. Configuration now makes read benign - errors warnings and write benign errors to errors by default (thus - changing the behavior on read). The simplified API always forces - read benign errors to warnings (regardless of the system default, unless - this is disabled in which case the simplified API can't be built.) - -Version 1.6.0beta19 [March 18, 2012] - Work around for duplicate row start calls; added warning messages. - This turns on PNG_FLAG_DETECT_UNINITIALIZED to detect app code that - fails to call one of the 'start' routines (not enabled in libpng-1.5 - because it is technically an API change, since it did normally work - before.) It also makes duplicate calls to png_read_start_row (an - internal function called at the start of the image read) benign, as - they were before changes to use png_inflate_claim. Somehow webkit is - causing this to happen; this is probably a mis-feature in the zlib - changes so this commit is only a work-round. - Removed erroneous setting of DETECT_UNINITIALIZED and added more - checks. The code now does a png_error if an attempt is made to do the - row initialization twice; this is an application error and it has - serious consequences because the transform data in png_struct is - changed by each call. - Added application error reporting and added chunk names to read - benign errors; also added --strict to pngstest - not enabled - yet because a warning is produced. - Avoid the double gamma correction warning in the simplified API. - This allows the --strict option to pass in the pngstest checks - -Version 1.6.0beta20 [March 29, 2012] - Changed chunk handler warnings into benign errors, incrementally load iCCP - Added checksum-icc.c to contrib/tools - Prevent PNG_EXPAND+PNG_SHIFT doing the shift twice. - Recognize known sRGB ICC profiles while reading; prefer writing the - iCCP profile over writing the sRGB chunk, controlled by the - PNG_sRGB_PROFILE_CHECKS option. - Revised png_set_text_2() to avoid potential memory corruption (fixes - CVE-2011-3048, also known as CVE-2012-3425). - -Version 1.6.0beta21 [April 27, 2012] - Revised scripts/makefile.darwin: use system zlib; remove quotes around - architecture list; add missing ppc architecture; add architecture options - to shared library link; don't try to create a shared lib based on missing - RELEASE variable. - Enable png_set_check_for_invalid_index() for both read and write. - Removed #ifdef PNG_HANDLE_AS_UNKNOWN_SUPPORTED in pngpriv.h around - declaration of png_handle_unknown(). - Added -lssp_nonshared in a comment in scripts/makefile.freebsd - and changed deprecated NOOBJ and NOPROFILE to NO_OBJ and NO_PROFILE. - -Version 1.6.0beta22 [May 23, 2012] - Removed need for -Wno-cast-align with clang. clang correctly warns on - alignment increasing pointer casts when -Wcast-align is passed. This - fixes the cases that clang warns about either by eliminating the - casts from png_bytep to png_uint_16p (pngread.c), or, for pngrutil.c - where the cast is previously verified or pngstest.c where it is OK, by - introducing new png_aligncast macros to do the cast in a way that clang - accepts. - -Version 1.6.0beta23 [June 6, 2012] - Revised CMakeLists.txt to not attempt to make a symlink under mingw. - Made fixes for new optimization warnings from gcc 4.7.0. The compiler - performs an optimization which is safe; however it then warns about it. - Changing the type of 'palette_number' in pngvalid.c removes the warning. - Do not depend upon a GCC feature macro being available for use in generating - the linker mapfile symbol prefix. - Improved performance of new do_check_palette_indexes() function (only - update the value when it actually increases, move test for whether - the check is wanted out of the function. - -Version 1.6.0beta24 [June 7, 2012] - Don't check palette indexes if num_palette is 0 (as it can be in MNG files). - -Version 1.6.0beta25 [June 16, 2012] - Revised png_set_keep_unknown_chunks() so num_chunks < 0 means ignore all - unknown chunks and all known chunks except for IHDR, PLTE, tRNS, IDAT, - and IEND. Previously it only meant ignore all unknown chunks, the - same as num_chunks == 0. Revised png_image_skip_unused_chunks() to - provide a list of chunks to be processed instead of a list of chunks to - ignore. Revised contrib/gregbook/readpng2.c accordingly. - -Version 1.6.0beta26 [July 10, 2012] - Removed scripts/makefile.cegcc from the *.zip and *.7z distributions; it - depends on configure, which is not included in those archives. - Moved scripts/chkfmt to contrib/tools. - Changed "a+w" to "u+w" in Makefile.in to fix CVE-2012-3386. - -Version 1.6.0beta27 [August 11, 2012] - Do not compile PNG_DEPRECATED, PNG_ALLOC and PNG_PRIVATE when __GNUC__ < 3. - Do not use __restrict when GNUC is <= 3.1 - Removed references to png_zalloc() and png_zfree() from the manual. - Fixed configurations where floating point is completely disabled. Because - of the changes to support symbol prefixing PNG_INTERNAL_FUNCTION declares - floating point APIs during libpng builds even if they are completely - disabled. This requires the png floating point types (png_double*) to be - declared even though the functions are never actually defined. This - change provides a dummy definition so that the declarations work, yet any - implementation will fail to compile because of an incomplete type. - Re-eliminated the use of strcpy() in pngtest.c. An unncessary use of - strcpy() was accidentally re-introduced in libpng16; this change replaces - it with strncpy(). - Eliminated use of png_sizeof(); use sizeof() instead. - Use a consistent style for (sizeof type) and (sizeof (array)) - Cleanup of png_set_filler(). This function does very different things on - read and write. In libpng 1.6 the two cases can be distinguished and - considerable code cleanup, and extra error checking, is possible. This - makes calls on the write side that have no effect be ignored with a - png_app_error(), which can be disabled in the app using - png_set_benign_errors(), and removes the spurious use of usr_channels - on the read side. - Insist on autotools 1.12.1 for git builds because there are security issues - with 1.12 and insisting on anything less would allow 1.12 to be used. - Removed info_ptr->signature[8] from WRITE-only builds. - Add some conditions for compiling png_fixed(). This is a small function - but it requires "-lm" on some platforms. - Cause pngtest --strict to fail on any warning from libpng (not just errors) - and cause it not to fail at the comparison step if libpng lacks support - for writing chunks that it reads from the input (currently only implemented - for compressed text chunks). - Make all three "make check" test programs work without READ or WRITE support. - Now "make check" will succeed even if libpng is compiled with -DPNG_NO_READ - or -DPNG_NO_WRITE. The tests performed are reduced, but the basic reading - and writing of a PNG file is always tested by one or more of the tests. - Consistently use strlen(), memset(), memcpy(), and memcmp() instead of the - png_strlen(), png_memset(), png_memcpy(), and png_memcmp() macros. - Removed the png_sizeof(), png_strlen(), png_memset(), png_memcpy(), and - png_memcmp() macros. - Work around gcc 3.x and Microsoft Visual Studio 2010 complaints. Both object - to the split initialization of num_chunks. - -Version 1.6.0beta28 [August 29, 2012] - Unknown handling fixes and clean up. This adds more correct option - control of the unknown handling, corrects the pre-existing bug where - the per-chunk 'keep' setting is ignored and makes it possible to skip - IDAT chunks in the sequential reader (broken in earlier 1.6 versions). - There is a new test program, test-unknown.c, which is a work in progress - (not currently part of the test suite). Comments in the header files now - explain how the unknown handling works. - Allow fine grain control of unknown chunk APIs. This change allows - png_set_keep_unknown_chunks() to be turned off if not required and causes - both read and write to behave appropriately (on read this is only possible - if the user callback is used to handle unknown chunks). The change - also removes the support for storing unknown chunks in the info_struct - if the only unknown handling enabled is via the callback, allowing libpng - to be configured with callback reading and none of the unnecessary code. - Corrected fix for unknown handling in pngtest. This reinstates the - libpng handling of unknown chunks other than vpAg and sTER (including - unsafe-to-copy chunks which were dropped before) and eliminates the - repositioning of vpAg and sTER in pngtest.png by changing pngtest.png - (so the chunks are where libpng would put them). - Added "tunknown" test and corrected a logic error in png_handle_unknown() - when SAVE support is absent. Moved the shell test scripts for - contrib/libtests from the libpng top directory to contrib/libtests. - png_handle_unknown() must always read or skip the chunk, if - SAVE_UNKNOWN_CHUNKS is turned off *and* the application does not set - a user callback an unknown chunk will not be read, leading to a read - error, which was revealed by the "tunknown" test. - Cleaned up and corrected ICC profile handling. - contrib/libtests/makepng: corrected 'rgb' and 'gray' cases. profile_error - messages could be truncated; made a correct buffer size calculation and - adjusted pngerror.c appropriately. png_icc_check_* checking improved; - changed the functions to receive the correct color type of the PNG on read - or write and check that it matches the color space of the profile (despite - what the comments said before, there is danger in assuming the app will - cope correctly with an RGB profile on a grayscale image and, since it - violates the PNG spec, allowing it is certain to produce inconsistent - app behavior and might even cause app crashes.) Check that profiles - contain the tags needed to process the PNG (tags all required by the ICC - spec). Removed unused PNG_STATIC from pngpriv.h. - -Version 1.6.0beta29 [September 4, 2012] - Fixed the simplified API example programs to add the *colormap parameter - to several of he API and improved the error message if the version field - is not set. - Added contrib/examples/* to the *.zip and *.7z distributions. - Updated simplified API synopses and description of the png_image structure - in the manual. - Made makepng and pngtest produce identical PNGs, add "--relaxed" option - to pngtest. The "--relaxed" option turns off the benign errors that are - enabled by default in pre-RC builds. makepng can now write ICC profiles - where the length has not been extended to a multiple of 4, and pngtest - now intercepts all libpng errors, allowing the previously-introduced - "--strict test" on no warnings to actually work. - Improved ICC profile handling including cHRM chunk generation and fixed - Cygwin+MSVC build errors. The ICC profile handling now includes more - checking. Several errors that caused rejection of the profile are now - handled with a warning in such a way that the invalid profiles will be - read by default in release (but not pre-RC) builds but will not be - written by default. The easy part of handling the cHRM chunk is written, - where the ICC profile contains the required data. The more difficult - part plus guessing a gAMA value requires code to pass selected RGB values - through the profile. - -Version 1.6.0beta30 [October 24, 2012] - Changed ICC profile matrix/vector types to not depend on array type rules. - By the ANSI-C standard the new types should be identical to the previous - versions, and all known versions of gcc tested with the previous versions - except for GCC-4.2.1 work with this version. The change makes the ANSI-C - rule that const applied to an array of elements applies instead to the - elements in the array moot by explicitly applying const to the base - elements of the png_icc_matrix and png_icc_vector types. The accidental - (harmless) 'const' previously applied to the parameters of two of the - functions have also been removed. - Added a work around for GCC 4.2 optimization bug. - Marked the broken (bad white point) original HP sRGB profiles correctly and - correct comments. - Added -DZ_SOLO to contrib/pngminim/*/makefile to work with zlib-1.2.7 - Use /MDd for vstudio debug builds. Also added pngunkown to the vstudio - builds, fixed build errors and corrected a minor exit code error in - pngvalid if the 'touch' file name is invalid. - Add updated WARNING file to projects/vstudio from libpng 1.5/vstudio - Fixed build when using #define PNG_NO_READ_GAMMA in png_do_compose() in - pngrtran.c (Domani Hannes). - -Version 1.6.0beta31 [November 1, 2012] - Undid the erroneous change to vstudio/pngvalid build in libpng-1.6.0beta30. - Made pngvalid so that it will build outside the libpng source tree. - Made builds -DPNG_NO_READ_GAMMA compile (the unit tests still fail). - Made PNG_NO_READ_GAMMA switch off interfaces that depend on READ_GAMMA. - Prior to 1.6.0 switching off READ_GAMMA did unpredictable things to the - interfaces that use it (specifically, png_do_background in 1.4 would - simply display composite for grayscale images but do composition - with the incorrect arithmetic for color ones). In 1.6 the semantic - of -DPNG_NO_READ_GAMMA is changed to simply disable any interface that - depends on it; this obliges people who set it to consider whether they - really want it off if they happen to use any of the interfaces in - question (typically most users who disable it won't). - Fixed GUIDs in projects/vstudio. Some were duplicated or missing, - resulting in VS2010 having to update the files. - Removed non-working ICC profile support code that was mostly added to - libpng-1.6.0beta29 and beta30. There was too much code for too little - gain; implementing full ICC color correction may be desireable but is left - up to applications. - -Version 1.6.0beta32 [November 25, 2012] - Fixed an intermittent SEGV in pngstest due to an uninitialized array element. - Added the ability for contrib/libtests/makepng.c to make a PNG with just one - color. This is useful for debugging pngstest color inaccuracy reports. - Fixed error checking in the simplified write API (Olaf van der Spek) - Made png_user_version_check() ok to use with libpng version 1.10.x and later. - -Version 1.6.0beta33 [December 15, 2012] - Fixed typo in png.c (PNG_SET_CHUNK_MALLOC_MAX should be PNG_CHUNK_MALLOC_MAX) - that causes the MALLOC_MAX limit not to work (John Bowler) - Change png_warning() to png_app_error() in pngwrite.c and comment the - fall-through condition. - Change png_warning() to png_app_warning() in png_write_tRNS(). - Rearranged the ARM-NEON optimizations: Isolated the machine specific code - to the hardware subdirectory and added comments to pngrutil.c so that - implementors of other optimizations know what to do. - Fixed cases of unquoted DESTDIR in Makefile.am - Rebuilt Makefile.in, etc., with autoconf-2.69 and automake-1.12.5. - -Version 1.6.0beta34 [December 19, 2012] - Cleaned up whitespace in the synopsis portion of the manpage "libpng.3" - Disassembled the version number in scripts/options.awk (necessary for - building on SunOs). - -Version 1.6.0beta35 [December 23, 2012] - Made default Zlib compression settings be configurable. This adds #defines to - pnglibconf.h to control the defaults. - Fixed Windows build issues, enabled ARM compilation. Various warnings issued - by earlier versions of GCC fixed for Cygwin and Min/GW (which both use old - GCCs.) ARM support is enabled by default in zlib.props (unsupported by - Microsoft) and ARM compilation is made possible by deleting the check for - x86. The test programs cannot be run because they are not signed. - -Version 1.6.0beta36 [January 2, 2013] - Discontinued distributing libpng-1.x.x.tar.bz2. - Discontinued distributing libpng-1.7.0-1.6.0-diff.txt and similar. - Rebuilt configure with autoconf-2.69 (inadvertently not done in beta33) - Fixed 'make distcheck' on SUN OS - libpng.so was not being removed - -Version 1.6.0beta37 [January 10, 2013] - Fixed conceivable but difficult to repro overflow. Also added two test - programs to generate and test a PNG which should have the problem. - -Version 1.6.0beta39 [January 19, 2013] - Again corrected attempt at overflow detection in png_set_unknown_chunks() - (CVE-2013-7353). Added overflow detection in png_set_sPLT() and - png_set_text_2() (CVE-2013-7354). - -Version 1.6.0beta40 [January 20, 2013] - Use consistent handling of overflows in text, sPLT and unknown png_set_* APIs - -Version 1.6.0rc01 [January 26, 2013] - No changes. - -Version 1.6.0rc02 [February 4, 2013] - Added png_get_palette_max() function. - -Version 1.6.0rc03 [February 5, 2013] - Fixed the png_get_palette_max API. - -Version 1.6.0rc04 [February 7, 2013] - Turn serial tests back on (recently turned off by autotools upgrade). - -Version 1.6.0rc05 [February 8, 2013] - Update manual about png_get_palette_max(). - -Version 1.6.0rc06 [February 9, 2013] - Fixed missing dependency in --prefix builds The intermediate - internal 'prefix.h' file can only be generated correctly after - pnglibconf.h, however the dependency was not in Makefile.am. The - symptoms are unpredictable depending on the order make chooses to - build pngprefix.h and pnglibconf.h, often the error goes unnoticed - because there is a system pnglibconf.h to use instead. - -Version 1.6.0rc07 [February 10, 2013] - Enclosed the new png_get_palette_max in #ifdef PNG_GET_PALETTE_MAX_SUPPORTED - block, and revised pnglibconf.h and pnglibconf.h.prebuilt accordingly. - -Version 1.6.0rc08 [February 10, 2013] - Fix typo in png.h #ifdef - -Version 1.6.0 [February 14, 2013] - No changes. - -Version 1.6.1beta01 [February 16, 2013] - Made symbol prefixing work with the ARM neon optimizations. Also allow - pngpriv.h to be included for preprocessor definitions only, so it can - be used in non-C/C++ files. Back ported from libpng 1.7. - Made sRGB check numbers consistent. - Ported libpng 1.5 options.awk/dfn file handling to 1.6, fixed one bug. - Removed cc -E workround, corrected png_get_palette_max API Tested on - SUN OS cc 5.9, which demonstrates the tokenization problem previously - avoided by using /lib/cpp. Since all .dfn output is now protected in - double quotes unless it is to be macro substituted the fix should - work everywhere. - Enabled parallel tests - back ported from libpng-1.7. - scripts/pnglibconf.dfa formatting improvements back ported from libpng17. - Fixed a race condition in the creation of the build 'scripts' directory - while building with a parallel make. - Use approved/supported Android method to check for NEON, use Linux/POSIX - 1003.1 API to check /proc/self/auxv avoiding buffer allocation and other - library calls (ported from libpng15). - -Version 1.6.1beta02 [February 19, 2013] - Use parentheses more consistently in "#if defined(MACRO)" tests. - Folded long lines. - Reenabled code to allow zero length PLTE chunks for MNG. - -Version 1.6.1beta03 [February 22, 2013] - Fixed ALIGNED_MEMORY support. - Added a new configure option: - --enable-arm-neon=always will stop the run-time checks. New checks - within arm/arm_init.c will cause the code not to be compiled unless - __ARM_NEON__ is set. This should make it fail safe (if someone asks - for it on then the build will fail if it can't be done.) - Updated the INSTALL document. - -Version 1.6.1beta04 [February 27, 2013] - Revised INSTALL to recommend using CPPFLAGS instead of INCLUDES. - Revised scripts/makefile.freebsd to respect ZLIBLIB and ZLIBINC. - Revised scripts/dfn.awk to work with the buggy MSYS awk that has trouble - with CRLF line endings. - -Version 1.6.1beta05 [March 1, 2013] - Avoid a possible memory leak in contrib/gregbook/readpng.c - -Version 1.6.1beta06 [March 4, 2013] - Better documentation of unknown handling API interactions. - Corrected Android builds and corrected libpng.vers with symbol - prefixing. It also makes those tests compile and link on Android. - Added an API png_set_option() to set optimization options externally, - providing an alternative and general solution for the non-portable - run-time tests used by the ARM Neon code, using the PNG_ARM_NEON option. - The order of settings vs options in pnglibconf.h is reversed to allow - settings to depend on options and options can now set (or override) the - defaults for settings. - -Version 1.6.1beta07 [March 7, 2013] - Corrected simplified API default gamma for color-mapped output, added - a flag to change default. In 1.6.0 when the simplified API was used - to produce color-mapped output from an input image with no gamma - information the gamma assumed for the input could be different from - that assumed for non-color-mapped output. In particular 16-bit depth - input files were assumed to be sRGB encoded, whereas in the 'direct' - case they were assumed to have linear data. This was an error. The - fix makes the simplified API treat all input files the same way and - adds a new flag to the png_image::flags member to allow the - application/user to specify that 16-bit files contain sRGB data - rather than the default linear. - Fixed bugs in the pngpixel and makepng test programs. - -Version 1.6.1beta08 [March 7, 2013] - Fixed CMakelists.txt to allow building a single variant of the library - (Claudio Bley): - Introduced a PNG_LIB_TARGETS variable that lists all activated library - targets. It is an error if this variable ends up empty, ie. you have - to build at least one library variant. - Made the *_COPY targets only depend on library targets actually being build. - Use PNG_LIB_TARGETS to unify a code path. - Changed the CREATE_SYMLINK macro to expect the full path to a file as the - first argument. When symlinking the filename component of that path is - determined and used as the link target. - Use copy_if_different in the CREATE_SYMLINK macro. - -Version 1.6.1beta09 [March 13, 2013] - Eliminated two warnings from the Intel C compiler. The warnings are - technically valid, although a reasonable treatment of division would - show it to be incorrect. - -Version 1.6.1rc01 [March 21, 2013] - No changes. - -Version 1.6.1 [March 28, 2013] - No changes. - -Version 1.6.2beta01 [April 14, 2013] - Updated documentation of 1.5.x to 1.6.x changes in iCCP chunk handling. - Fixed incorrect warning of excess deflate data. End condition - the - warning would be produced if the end of the deflate stream wasn't read - in the last row. The warning is harmless. - Corrected the test on user transform changes on read. It was in the - png_set of the transform function, but that doesn't matter unless the - transform function changes the rowbuf size, and that is only valid if - transform_info is called. - Corrected a misplaced closing bracket in contrib/libtests/pngvalid.c - (Flavio Medeiros). - Corrected length written to uncompressed iTXt chunks (Samuli Suominen). - Bug was introduced in libpng-1.6.0. - -Version 1.6.2rc01 [April 18, 2013] - Added contrib/tools/fixitxt.c, to repair the erroneous iTXt chunk length - written by libpng-1.6.0 and 1.6.1. - Disallow storing sRGB information when the sRGB is not supported. - -Version 1.6.2rc02 [April 18, 2013] - Merge pngtest.c with libpng-1.7.0 - -Version 1.6.2rc03 [April 22, 2013] - Trivial spelling cleanup. - -Version 1.6.2rc04 and 1.6.2rc05 [omitted] - -Version 1.6.2rc06 [April 24, 2013] - Reverted to version 1.6.2rc03. Recent changes to arm/neon support - have been ported to libpng-1.7.0beta09 and will reappear in version - 1.6.3beta01. - -Version 1.6.2 [April 25, 2013] - No changes. - -Version 1.6.3beta01 [April 25, 2013] - Revised stack marking in arm/filter_neon.S and configure.ac. - Ensure that NEON filter stuff is completely disabled when switched 'off'. - Previously the ARM NEON specific files were still built if the option - was switched 'off' as opposed to being explicitly disabled. - -Version 1.6.3beta02 [April 26, 2013] - Test for 'arm*' not just 'arm' in the host_cpu configure variable. - Rebuilt the configure scripts. - -Version 1.6.3beta03 [April 30, 2013] - Expanded manual paragraph about writing private chunks, particularly - the need to call png_set_keep_unknown_chunks() when writing them. - Avoid dereferencing NULL pointer possibly returned from - png_create_write_struct() (Andrew Church). - -Version 1.6.3beta05 [May 9, 2013] - Calculate our own zlib windowBits when decoding rather than trusting the - CMF bytes in the PNG datastream. - Added an option to force maximum window size for inflating, which was - the behavior of libpng15 and earlier, via a new PNG_MAXIMUM_INFLATE_WINDOW - option for png_set_options(). - Added png-fix-itxt and png-fix-too-far-back to the built programs and - removed warnings from the source code and timepng that are revealed as - a result. - Detect wrong libpng versions linked to png-fix-too-far-back, which currently - only works with libpng versions that can be made to reliably fail when - the deflate data contains an out-of-window reference. This means only - 1.6 and later. - Fixed gnu issues: g++ needs a static_cast, gcc 4.4.7 has a broken warning - message which it is easier to work round than ignore. - Updated contrib/pngminus/pnm2png.c (Paul Stewart): - Check for EOF - Ignore "#" delimited comments in input file to pnm2png.c. - Fixed whitespace handling - Added a call to png_set_packing() - Initialize dimension values so if sscanf fails at least we have known - invalid values. - Attempt to detect configuration issues with png-fix-too-far-back, which - requires both the correct libpng and the correct zlib to function - correctly. - Check ZLIB_VERNUM for mismatches, enclose #error in quotes - Added information in the documentation about problems with and fixes for - the bad CRC and bad iTXt chunk situations. - -Version 1.6.3beta06 [May 12, 2013] - Allow contrib/pngminus/pnm2png.c to compile without WRITE_INVERT and - WRITE_PACK supported (writes error message that it can't read P1 or - P4 PBM files). - Improved png-fix-too-far-back usage message, added --suffix option. - Revised contrib/pngminim/*/makefile to generate pnglibconf.h with the - right zlib header files. - Separated CPPFLAGS and CFLAGS in contrib/pngminim/*/makefile - -Version 1.6.3beta07 [June 8, 2013] - Removed a redundant test in png_set_IHDR(). - Added set(CMAKE_CONFIGURATION_TYPES ...) to CMakeLists.txt (Andrew Hundt) - Deleted set(CMAKE_BUILD_TYPE) block from CMakeLists.txt - Enclose the prototypes for the simplified write API in - #ifdef PNG_STDIO_SUPPORTED/#endif - Make ARM NEON support work at compile time (not just configure time). - This moves the test on __ARM_NEON__ into pngconf.h to avoid issues when - using a compiler that compiles for multiple architectures at one time. - Removed PNG_FILTER_OPTIMIZATIONS and PNG_ARM_NEON_SUPPORTED from - pnglibconf.h, allowing more of the decisions to be made internally - (pngpriv.h) during the compile. Without this, symbol prefixing is broken - under certain circumstances on ARM platforms. Now only the API parts of - the optimizations ('check' vs 'api') are exposed in the public header files - except that the new setting PNG_ARM_NEON_OPT documents how libpng makes the - decision about whether or not to use the optimizations. - Protect symbol prefixing against CC/CPPFLAGS/CFLAGS useage. - Previous iOS/Xcode fixes for the ARM NEON optimizations moved the test - on __ARM_NEON__ from configure time to compile time. This breaks symbol - prefixing because the definition of the special png_init_filter_functions - call was hidden at configure time if the relevant compiler arguments are - passed in CFLAGS as opposed to CC. This change attempts to avoid all - the confusion that would result by declaring the init function even when - it is not used, so that it will always get prefixed. - -Version 1.6.3beta08 [June 18, 2013] - Revised libpng.3 so that "doclifter" can process it. - -Version 1.6.3beta09 [June 27, 2013] - Revised example.c to illustrate use of PNG_DEFAULT_sRGB and PNG_GAMMA_MAC_18 - as parameters for png_set_gamma(). These have been available since - libpng-1.5.4. - Renamed contrib/tools/png-fix-too-far-back.c to pngfix.c and revised it - to check all compressed chunks known to libpng. - -Version 1.6.3beta10 [July 5, 2013] - Updated documentation to show default behavior of benign errors correctly. - Only compile ARM code when PNG_READ_SUPPORTED is defined. - Fixed undefined behavior in contrib/tools/pngfix.c and added new strip - option. pngfix relied on undefined behavior and even a simple change from - gcc to g++ caused it to fail. The new strip option 'unsafe' has been - implemented and is the default if --max is given. Option names have - been clarified, with --strip=transform now stripping the bKGD chunk, - which was stripped previously with --strip=unused. - Added all documented chunk types to pngpriv.h - Unified pngfix.c source with libpng17. - -Version 1.6.3rc01 [July 11, 2013] - No changes. - -Version 1.6.3 [July 18, 2013] - Revised manual about changes in iTXt chunk handling made in libpng-1.6.0. - Added "/* SAFE */" comments in pngrutil.c and pngrtran.c where warnings - may be erroneously issued by code-checking applications. - -Version 1.6.4beta01 [August 21, 2013] - Added information about png_set_options() to the manual. - Delay calling png_init_filter_functions() until a row with nonzero filter - is found. - -Version 1.6.4beta02 [August 30, 2013] - Fixed inconsistent conditional compilation of png_chunk_unknown_handling() - prototype, definition, and usage. Made it depend on - PNG_HANDLE_AS_UNKNOWN_SUPPORTED everywhere. - -Version 1.6.4rc01 [September 5, 2013] - No changes. - -Version 1.6.4 [September 12, 2013] - No changes. - -Version 1.6.5 [September 14, 2013] - Removed two stray lines of code from arm/arm_init.c. - -Version 1.6.6 [September 16, 2013] - Removed two stray lines of code from arm/arm_init.c, again. - -Version 1.6.7beta01 [September 30, 2013] - Revised unknown chunk code to correct several bugs in the NO_SAVE_/NO_WRITE - combination - Allow HANDLE_AS_UNKNOWN to work when other options are configured off. Also - fixed the pngminim makefiles to work when $(MAKEFLAGS) contains stuff - which terminates the make options (as by default in recent versions of - Gentoo). - Avoid up-cast warnings in pngvalid.c. On ARM the alignment requirements of - png_modifier are greater than that of png_store and as a consequence - compilation of pngvalid.c results in a warning about increased alignment - requirements because of the bare cast to (png_modifier*). The code is safe, - because the pointer is known to point to a stack allocated png_modifier, - but this change avoids the warning. - Fixed default behavior of ARM_NEON_API. If the ARM NEON API option was - compiled without the CHECK option it defaulted to on, not off. - Check user callback behavior in pngunknown.c. Previous versions compiled - if SAVE_UNKNOWN was not available but did nothing since the callback - was never implemented. - Merged pngunknown.c with 1.7 version and back ported 1.7 improvements/fixes - -Version 1.6.7beta02 [October 12, 2013] - Made changes for compatibility with automake 1.14: - 1) Added the 'compile' program to the list of programs that must be cleaned - in autogen.sh - 2) Added 'subdir-objects' which causes .c files in sub-directories to be - compiled such that the corresponding .o files are also in the - sub-directory. This is because automake 1.14 warns that the - current behavior of compiling to the top level directory may be removed - in the future. - 3) Updated dependencies on pnglibconf.h to match the new .o locations and - added all the files in contrib/libtests and contrib/tools that depend - on pnglibconf.h - 4) Added 'BUILD_SOURCES = pnglibconf.h'; this is the automake recommended - way of handling the dependencies of sources that are machine generated; - unfortunately it only works if the user does 'make all' or 'make check', - so the dependencies (3) are still required. - Cleaned up (char*) casts of zlib messages. The latest version of the Intel C - compiler complains about casting a string literal as (char*), so copied the - treatment of z_const from the library code into pngfix.c - Simplified error message code in pngunknown. The simplification has the - useful side effect of avoiding a bogus warning generated by the latest - version of the Intel C compiler (it objects to - condition ? string-literal : string-literal). - Make autogen.sh work with automake 1.13 as well as 1.14. Do this by always - removing the 1.14 'compile' script but never checking for it. - -Version 1.6.7beta03 [October 19, 2013] - Added ARMv8 support (James Yu ). Added file - arm/filter_neon_intrinsics.c; enable with -mfpu=neon. - Revised pngvalid to generate size images with as many filters as it can - manage, limited by the number of rows. - Cleaned up ARM NEON compilation handling. The tests are now in pngpriv.h - and detect the broken GCC compilers. - -Version 1.6.7beta04 [October 26, 2013] - Allow clang derived from older GCC versions to use ARM intrinsics. This - causes all clang builds that use -mfpu=neon to use the intrinsics code, - not the assembler code. This has only been tested on iOS 7. It may be - necessary to exclude some earlier clang versions but this seems unlikely. - Changed NEON implementation selection mechanism. This allows assembler - or intrinsics to be turned on at compile time during the build by defining - PNG_ARM_NEON_IMPLEMENTATION to the correct value (2 or 1). This macro - is undefined by default and the build type is selected in pngpriv.h. - -Version 1.6.7rc01 [November 2, 2013] - No changes. - -Version 1.6.7rc02 [November 7, 2013] - Fixed #include in filter_neon_intrinsics.c and ctype macros. The ctype char - checking macros take an unsigned char argument, not a signed char. - -Version 1.6.7 [November 14, 2013] - No changes. - -Version 1.6.8beta01 [November 24, 2013] - Moved prototype for png_handle_unknown() in pngpriv.h outside of - the #ifdef PNG_SET_UNKNOWN_CHUNKS_SUPPORTED/#endif block. - Added "-Wall" to CFLAGS in contrib/pngminim/*/makefile - Conditionally compile some unused functions reported by -Wall in - pngminim. - Fixed 'minimal' builds. Various obviously useful minimal configurations - don't build because of missing contrib/libtests test programs and - overly complex dependencies in scripts/pnglibconf.dfa. This change - adds contrib/conftest/*.dfa files that can be used in automatic build - scripts to ensure that these configurations continue to build. - Enabled WRITE_INVERT and WRITE_PACK in contrib/pngminim/encoder. - Fixed pngvalid 'fail' function declaration on the Intel C Compiler. - This reverts to the previous 'static' implementation and works round - the 'unused static function' warning by using PNG_UNUSED(). - -Version 1.6.8beta02 [November 30, 2013] - Removed or marked PNG_UNUSED some harmless "dead assignments" reported - by clang scan-build. - Changed tabs to 3 spaces in png_debug macros and changed '"%s"m' - to '"%s" m' to improve portability among compilers. - Changed png_free_default() to free() in pngtest.c - -Version 1.6.8rc01 [December 12, 2013] - Tidied up pngfix inits and fixed pngtest no-write builds. - -Version 1.6.8rc02 [December 14, 2013] - Handle zero-length PLTE chunk or NULL palette with png_error() - instead of png_chunk_report(), which by default issues a warning - rather than an error, leading to later reading from a NULL pointer - (png_ptr->palette) in png_do_expand_palette(). This is CVE-2013-6954 - and VU#650142. Libpng-1.6.1 through 1.6.7 are vulnerable. - Libpng-1.6.0 and earlier do not have this bug. - -Version 1.6.8 [December 19, 2013] - No changes. - -Version 1.6.9beta01 [December 26, 2013] - Bookkeeping: Moved functions around (no changes). Moved transform - function definitions before the place where they are called so that - they can be made static. Move the intrapixel functions and the - grayscale palette builder out of the png?tran.c files. The latter - isn't a transform function and is no longer used internally, and the - former MNG specific functions are better placed in pngread/pngwrite.c - Made transform implementation functions static. This makes the internal - functions called by png_do_{read|write}_transformations static. On an - x86-64 DLL build (Gentoo Linux) this reduces the size of the text - segment of the DLL by 1208 bytes, about 0.6%. It also simplifies - maintenance by removing the declarations from pngpriv.h and allowing - easier changes to the internal interfaces. - Rebuilt configure scripts with automake-1.14.1 and autoconf-2.69 - in the tar distributions. - -Version 1.6.9beta02 [January 1, 2014] - Added checks for libpng 1.5 to pngvalid.c. This supports the use of - this version of pngvalid in libpng 1.5 - Merged with pngvalid.c from libpng-1.7 changes to create a single - pngvalid.c - Removed #error macro from contrib/tools/pngfix.c (Thomas Klausner). - Merged pngrio.c, pngtrans.c, pngwio.c, and pngerror.c with libpng-1.7.0 - Merged libpng-1.7.0 changes to make no-interlace configurations work - with test programs. - Revised pngvalid.c to support libpng 1.5, which does not support the - PNG_MAXIMUM_INFLATE_WINDOW option, so #define it out when appropriate in - pngvalid.c - Allow unversioned links created on install to be disabled in configure. - In configure builds 'make install' changes/adds links like png.h - and libpng.a to point to the newly installed, versioned, files (e.g. - libpng17/png.h and libpng17.a). Three new configure options and some - rearrangement of Makefile.am allow creation of these links to be disabled. - -Version 1.6.9beta03 [January 10, 2014] - Removed potentially misleading warning from png_check_IHDR(). - -Version 1.6.9beta04 [January 20, 2014] - Updated scripts/makefile.* to use CPPFLAGS (Cosmin). - Added clang attribute support (Cosmin). - -Version 1.6.9rc01 [January 28, 2014] - No changes. - -Version 1.6.9rc02 [January 30, 2014] - Quiet an uninitialized memory warning from VC2013 in png_get_png(). - -Version 1.6.9 [February 6, 2014] - -Version 1.6.10beta01 [February 9, 2014] - Backported changes from libpng-1.7.0beta30 and beta31: - Fixed a large number of instances where PNGCBAPI was omitted from - function definitions. - Added pngimage test program for png_read_png() and png_write_png() - with two new test scripts. - Removed dependence on !PNG_READ_EXPAND_SUPPORTED for calling - png_set_packing() in png_read_png(). - Fixed combination of ~alpha with shift. On read invert alpha, processing - occurred after shift processing, which causes the final values to be - outside the range that should be produced by the shift. Reversing the - order on read makes the two transforms work together correctly and mirrors - the order used on write. - Do not read invalid sBIT chunks. Previously libpng only checked sBIT - values on write, so a malicious PNG writer could therefore cause - the read code to return an invalid sBIT chunk, which might lead to - application errors or crashes. Such chunks are now skipped (with - chunk_benign_error). - Make png_read_png() and png_write_png() prototypes in png.h depend - upon PNG_READ_SUPPORTED and PNG_WRITE_SUPPORTED. - Support builds with unsupported PNG_TRANSFORM_* values. All of the - PNG_TRANSFORM_* values are always defined in png.h and, because they - are used for both read and write in some cases, it is not reliable - to #if out ones that are totally unsupported. This change adds error - detection in png_read_image() and png_write_image() to do a - png_app_error() if the app requests something that cannot be done - and it adds corresponding code to pngimage.c to handle such options - by not attempting to test them. - -Version 1.6.10beta02 [February 23, 2014] - Moved redefines of png_error(), png_warning(), png_chunk_error(), - and png_chunk_warning() from pngpriv.h to png.h to make them visible - to libpng-calling applications. - Moved OS dependent code from arm/arm_init.c, to allow the included - implementation of the ARM NEON discovery function to be set at - build-time and provide sample implementations from the current code in the - contrib/arm-neon subdirectory. The __linux__ code has also been changed to - compile and link on Android by using /proc/cpuinfo, and the old linux code - is in contrib/arm-neon/linux-auxv.c. The new code avoids POSIX and Linux - dependencies apart from opening /proc/cpuinfo and is C90 compliant. - Check for info_ptr == NULL early in png_read_end() so we don't need to - run all the png_handle_*() and depend on them to return if info_ptr == NULL. - This improves the performance of png_read_end(png_ptr, NULL) and makes - it more robust against future programming errors. - Check for __has_extension before using it in pngconf.h, to - support older Clang versions (Jeremy Sequoia). - Treat CRC error handling with png_set_crc_action(), instead of with - png_set_benign_errors(), which has been the case since libpng-1.6.0beta18. - Use a user warning handler in contrib/gregbook/readpng2.c instead of default, - so warnings will be put on stderr even if libpng has CONSOLE_IO disabled. - Added png_ptr->process_mode = PNG_READ_IDAT_MODE in png_push_read_chunk - after recognizing the IDAT chunk, which avoids an infinite loop while - reading a datastream whose first IDAT chunk is of zero-length. - This fixes CERT VU#684412 and CVE-2014-0333. - Don't recognize known sRGB profiles as sRGB if they have been hacked, - but don't reject them and don't issue a copyright violation warning. - -Version 1.6.10beta03 [February 25, 2014] - Moved some documentation from png.h to libpng.3 and libpng-manual.txt - Minor editing of contrib/arm-neon/README and contrib/examples/*.c - -Version 1.6.10rc01 [February 27, 2014] - Fixed typos in the manual and in scripts/pnglibconf.dfa (CFLAGS -> CPPFLAGS - and PNG_USR_CONFIG -> PNG_USER_CONFIG). - -Version 1.6.10rc02 [February 28, 2014] - Removed unreachable return statement after png_chunk_error() - in pngrutil.c - -Version 1.6.10rc03 [March 4, 2014] - Un-deprecated png_data_freer(). - -Version 1.6.10 [March 6, 2014] - No changes. - -Version 1.6.11beta01 [March 17, 2014] - Use "if (value != 0)" instead of "if (value)" consistently. - Changed ZlibSrcDir from 1.2.5 to 1.2.8 in projects/vstudio. - Moved configuration information from the manual to the INSTALL file. - -Version 1.6.11beta02 [April 6, 2014] - Removed #if/#else/#endif from inside two pow() calls in pngvalid.c because - they were handled improperly by Portland Group's PGI-14.1 - PGI-14.3 - when using its "__builtin_pow()" function. - Silence 'unused parameter' build warnings (Cosmin Truta). - $(CP) is now used alongside $(RM_F). Also, use 'copy' instead of 'cp' - where applicable, and applied other minor makefile changes (Cosmin). - Don't warn about invalid dimensions exceeding user limits (Cosmin). - Allow an easy replacement of the default pre-built configuration - header with a custom header, via the make PNGLIBCONF_H_PREBUILT - macro (Cosmin). - -Version 1.6.11beta03 [April 6, 2014] - Fixed a typo in pngrutil.c, introduced in libpng-1.5.6, that interferes - with "blocky" expansion of sub-8-bit interlaced PNG files (Eric Huss). - Optionally use __builtin_bswap16() in png_do_swap(). - -Version 1.6.11beta04 [April 19, 2014] - Made progressive reading of interlaced images consistent with the - behavior of the sequential reader and consistent with the manual, by - moving some code out of the PNG_READ_INTERLACING_SUPPORTED blocks. The - row_callback now receives the proper pass number and unexpanded rows, when - png_combine_row() isn't built or used, and png_set_interlace_handling() - is not called. - Allow PNG_sRGB_PROFILE_CHECKING = (-1) to mean no sRGB profile checking. - -Version 1.6.11beta05 [April 26, 2014] - Do not reject ICC V2 profiles that lack padding (Kai-Uwe Behrmann). - Relocated closing bracket of the sRGB profile test loop to avoid getting - "Not recognizing known sRGB profile that has been edited" warning for - ICC V2 profiles that lack the MD5 signature in the profile header. - -Version 1.6.11beta06 [May 19, 2014] - Added PNG_SKIP_sRGB_CHECK_PROFILE choice for png_set_option(). - -Version 1.6.11rc01 [May 27, 2014] - No changes. - -Version 1.6.11rc02 [June 3, 2014] - Test ZLIB_VERNUM instead of PNG_ZLIB_VERNUM in contrib/tools/pngfix.c - -Version 1.6.11 [June 5, 2014] - No changes. - -Version 1.6.12rc01 [June 6, 2014] - Relocated new code from 1.6.11beta06 in png.c to a point after the - declarations (Max Stepin). - -Version 1.6.12rc02 [June 7, 2014] - Changed file permissions of contrib/tools/intgamma.sh, - test-driver, and compile from 0644 to 0755 (Cosmin). - -Version 1.6.12rc03 [June 8, 2014] - Ensure "__has_attribute()" macro exists before trying to use it with - old clang compilers (MacPorts Ticket #43939). - -Version 1.6.12 [June 12, 2014] - No changes. - -Version 1.6.13beta01 [July 4, 2014] - Quieted -Wsign-compare and -Wclobber compiler warnings in - contrib/pngminus/*.c - Added "(void) png_ptr;" where needed in contrib/gregbook to quiet - compiler complaints about unused pointers. - Split a long output string in contrib/gregbook/rpng2-x.c. - Added "PNG_SET_OPTION" requirement for sRGB chunk support to pnglibconf.dfa, - Needed for write-only support (John Bowler). - Changed "if defined(__ARM_NEON__)" to - "if (defined(__ARM_NEON__) || defined(__ARM_NEON))" (James Wu). - Fixed clang no-warning builds: png_digit was defined but never used. - -Version 1.6.13beta02 [July 21, 2014] - Fixed an incorrect separator ("/" should be "\") in scripts/makefile.vcwin32 - (bug report from Wolfgang S. Kechel). Bug was introduced in libpng-1.6.11. - Also fixed makefile.bc32, makefile.bor, makefile.msc, makefile.intel, and - makefile.tc3 similarly. - -Version 1.6.13beta03 [August 3, 2014] - Removed scripts/makefile.elf. It has not worked since libpng-1.5.0beta14 - due to elimination of the PNG_FUNCTION_EXPORT and PNG_DATA_EXPORT - definitions from pngconf.h. - Ensure that CMakeLists.txt makes the target "lib" directory before making - symbolic link into it (SourceForge bug report #226 by Rolf Timmermans). - -Version 1.6.13beta04 [August 8, 2014] - Added opinion that the ECCN (Export Control Classification Number) for - libpng is EAR99 to the README file. - Eliminated use of "$<" in makefile explicit rules, when copying - $PNGLIBCONF_H_PREBUILT. This does not work on some versions of make; - bug introduced in libpng version 1.6.11. - -Version 1.6.13rc01 [August 14, 2014] - Made "ccopts" agree with "CFLAGS" in scripts/makefile.hp* and makefile.*sunu - -Version 1.6.13 [August 21, 2014] - No changes. - -Version 1.6.14beta01 [September 14, 2014] - Guard usage of png_ptr->options with #ifdef PNG_SET_OPTION_SUPPORTED. - Do not build contrib/tools/pngfix.c when PNG_SETJMP_NOT_SUPPORTED, - to allow "make" to complete without setjmp support (bug report by - Claudio Fontana) - Add "#include " to contrib/tools/pngfix.c (John Bowler) - -Version 1.6.14beta02 [September 18, 2014] - Use nanosleep() instead of usleep() in contrib/gregbook/rpng2-x.c - because usleep() is deprecated. - Define usleep() in contrib/gregbook/rpng2-x.c if not already defined - in unistd.h and nanosleep() is not available; fixes error introduced - in libpng-1.6.13. - Disable floating point exception handling in pngvalid.c when - PNG_FLOATING_ARITHMETIC is not supported (bug report by "zootus - at users.sourceforge.net"). - -Version 1.6.14beta03 [September 19, 2014] - Define FE_DIVBYZERO, FE_INVALID, and FE_OVERFLOW in pngvalid.c if not - already defined. Revert floating point exception handling in pngvalid.c - to version 1.6.14beta01 behavior. - -Version 1.6.14beta04 [September 27, 2014] - Fixed incorrect handling of the iTXt compression flag in pngrutil.c - (bug report by Shunsaku Hirata). Bug was introduced in libpng-1.6.0. - -Version 1.6.14beta05 [October 1, 2014] - Added "option READ_iCCP enables READ_COMPRESSED_TEXT" to pnglibconf.dfa - -Version 1.6.14beta06 [October 5, 2014] - Removed unused "text_len" parameter from private function png_write_zTXt(). - Conditionally compile some code in png_deflate_claim(), when - PNG_WARNINGS_SUPPORTED and PNG_ERROR_TEXT_SUPPORTED are disabled. - Replaced repeated code in pngpread.c with PNG_PUSH_SAVE_BUFFER_IF_FULL. - Added "chunk iTXt enables TEXT" and "chunk zTXt enables TEXT" - to pnglibconf.dfa. - Removed "option READ_COMPRESSED_TEXT enables READ_TEXT" from pnglibconf.dfa, - to make it possible to configure a libpng that supports iCCP but not TEXT. - -Version 1.6.14beta07 [October 7, 2014] - Removed "option WRITE_COMPRESSED_TEXT enables WRITE_TEXT" from pnglibconf.dfa - Only mark text chunks as written after successfully writing them. - -Version 1.6.14rc01 [October 15, 2014] - Fixed some typos in comments. - -Version 1.6.14rc02 [October 17, 2014] - Changed png_convert_to_rfc_1123() to png_convert_to_rfc_1123_buffer() - in the manual, to reflect the change made in libpng-1.6.0. - Updated README file to explain that direct access to the png_struct - and info_struct members has not been permitted since libpng-1.5.0. - -Version 1.6.14 [October 23, 2014] - No changes. - -Version 1.6.15beta01 [October 29, 2014] - Changed "if (!x)" to "if (x == 0)" and "if (x)" to "if (x != 0)" - Simplified png_free_data(). - Added missing "ptr = NULL" after some instances of png_free(). - -Version 1.6.15beta02 [November 1, 2014] - Changed remaining "if (!x)" to "if (x == 0)" and "if (x)" to "if (x != 0)" - -Version 1.6.15beta03 [November 3, 2014] - Added PNG_USE_ARM_NEON configuration flag (Marcin Juszkiewicz). - -Version 1.6.15beta04 [November 4, 2014] - Removed new PNG_USE_ARM_NEON configuration flag and made a one-line - revision to configure.ac to support ARM on aarch64 instead (John Bowler). - -Version 1.6.15beta05 [November 5, 2014] - Use png_get_libpng_ver(NULL) instead of PNG_LIBPNG_VER_STRING in - example.c, pngtest.c, and applications in the contrib directory. - Fixed an out-of-range read in png_user_version_check() (Bug report from - Qixue Xiao, CVE-2015-8540). - Simplified and future-proofed png_user_version_check(). - Fixed GCC unsigned int->float warnings. Various versions of GCC - seem to generate warnings when an unsigned value is implicitly - converted to double. This is probably a GCC bug but this change - avoids the issue by explicitly converting to (int) where safe. - Free all allocated memory in pngimage. The file buffer cache was left - allocated at the end of the program, harmless but it causes memory - leak reports from clang. - Fixed array size calculations to avoid warnings. At various points - in the code the number of elements in an array is calculated using - sizeof. This generates a compile time constant of type (size_t) which - is then typically assigned to an (unsigned int) or (int). Some versions - of GCC on 64-bit systems warn about the apparent narrowing, even though - the same compiler does apparently generate the correct, in-range, - numeric constant. This adds appropriate, safe, casts to make the - warnings go away. - -Version 1.6.15beta06 [November 6, 2014] - Reverted use png_get_libpng_ver(NULL) instead of PNG_LIBPNG_VER_STRING - in the manual, example.c, pngtest.c, and applications in the contrib - directory. It was incorrect advice. - -Version 1.6.15beta07 [November 7, 2014] - Removed #ifdef PNG_16BIT_SUPPORTED/#endif around png_product2(); it is - needed by png_reciprocal2(). - Added #ifdef PNG_16BIT_SUPPORTED/#endif around png_log16bit() and - png_do_swap(). - Changed all "#endif /* PNG_FEATURE_SUPPORTED */" to "#endif /* FEATURE */" - -Version 1.6.15beta08 [November 8, 2014] - More housecleaning in *.h - -Version 1.6.15rc01 [November 13, 2014] - -Version 1.6.15rc02 [November 14, 2014] - The macros passed in the command line to Borland make were ignored if - similarly-named macros were already defined in makefiles. This behavior - is different from POSIX make and other make programs. Surround the - macro definitions with ifndef guards (Cosmin). - -Version 1.6.15rc03 [November 16, 2014] - Added "-D_CRT_SECURE_NO_WARNINGS" to CFLAGS in scripts/makefile.vcwin32. - Removed the obsolete $ARCH variable from scripts/makefile.darwin. - -Version 1.6.15 [November 20, 2014] - No changes. - -Version 1.6.16beta01 [December 14, 2014] - Added ".align 2" to arm/filter_neon.S to support old GAS assemblers that - don't do alignment correctly. - Revised Makefile.am and scripts/symbols.dfn to work with MinGW/MSYS - (Bob Friesenhahn). - -Version 1.6.16beta02 [December 15, 2014] - Revised Makefile.am and scripts/*.dfn again to work with MinGW/MSYS; - renamed scripts/*.dfn to scripts/*.c (John Bowler). - -Version 1.6.16beta03 [December 21, 2014] - Quiet a "comparison always true" warning in pngstest.c (John Bowler). - -Version 1.6.16rc01 [December 21, 2014] - Restored a test on width that was removed from png.c at libpng-1.6.9 - (Bug report by Alex Eubanks, CVE-2015-0973). - -Version 1.6.16rc02 [December 21, 2014] - Undid the update to pngrutil.c in 1.6.16rc01. - -Version 1.6.16rc03 [December 21, 2014] - Fixed an overflow in png_combine_row() with very wide interlaced images - (Bug report and fix by John Bowler, CVE-2014-9495). - -Version 1.6.16 [December 22, 2014] - No changes. - -Version 1.6.17beta01 [January 29, 2015] - Removed duplicate PNG_SAFE_LIMITS_SUPPORTED handling from pngconf.h - Corrected the width limit calculation in png_check_IHDR(). - Removed user limits from pngfix. Also pass NULL pointers to - png_read_row to skip the unnecessary row de-interlace stuff. - Added testing of png_set_packing() to pngvalid.c - Regenerated configure scripts in the *.tar distributions with libtool-2.4.4 - Implement previously untested cases of libpng transforms in pngvalid.c - Fixed byte order in png_do_read_filler() with 16-bit input. Previously - the high and low bytes of the filler, from png_set_filler() or from - png_set_add_alpha(), were read in the wrong order. - Made the check for out-of-range values in png_set_tRNS() detect - values that are exactly 2^bit_depth, and work on 16-bit platforms. - Merged some parts of libpng-1.6.17beta01 and libpng-1.7.0beta47. - Added #ifndef __COVERITY__ where needed in png.c, pngrutil.c and - pngset.c to avoid warnings about dead code. - Added "& 0xff" to many instances of expressions that are typecast - to (png_byte), to avoid Coverity warnings. - -Version 1.6.17beta02 [February 7, 2015] - Work around one more Coverity-scan dead-code warning. - Do not build png_product2() when it is unused. - -Version 1.6.17beta03 [February 17, 2015] - Display user limits in the output from pngtest. - Eliminated the PNG_SAFE_LIMITS macro and restored the 1-million-column - and 1-million-row default limits in pnglibconf.dfa, that can be reset - by the user at build time or run time. This provides a more robust - defense against DOS and as-yet undiscovered overflows. - -Version 1.6.17beta04 [February 21, 2015] - Added PNG_WRITE_CUSTOMIZE_COMPRESSION_SUPPORTED macro, on by default. - Allow user to call png_get_IHDR() with NULL arguments (Reuben Hawkins). - Rebuilt configure scripts with automake-1.15 and libtool-2.4.6 - -Version 1.6.17beta05 [February 25, 2015] - Restored compiling of png_reciprocal2 with PNG_NO_16BIT. - -Version 1.6.17beta06 [February 27, 2015] - Moved png_set_filter() prototype into a PNG_WRITE_SUPPORTED block - of png.h. - Avoid runtime checks when converting integer to png_byte with - Visual Studio (Sergey Kosarevsky) - -Version 1.6.17rc01 [March 4, 2015] - No changes. - -Version 1.6.17rc02 [March 9, 2015] - Removed some comments that the configure script did not handle - properly from scripts/pnglibconf.dfa and pnglibconf.h.prebuilt. - Free the unknown_chunks structure even when it contains no data. - -Version 1.6.17rc03 [March 12, 2015] - Updated CMakeLists.txt to add OSX framework, change YES/NO to ON/OFF - for consistency, and remove some useless tests (Alexey Petruchik). - -Version 1.6.17rc04 [March 16, 2015] - Remove pnglibconf.h, pnglibconf.c, and pnglibconf.out instead of - pnglibconf.* in "make clean" (Cosmin). - Fix bug in calculation of maxbits, in png_write_sBIT, introduced - in libpng-1.6.17beta01 (John Bowler). - -Version 1.6.17rc05 [March 21, 2015] - Define PNG_FILTER_* and PNG_FILTER_VALUE_* in png.h even when WRITE - is not supported (John Bowler). This fixes an error introduced in - libpng-1.6.17beta06. - Reverted "& 0xff" additions of version 1.6.17beta01. Libpng passes - the Coverity scan without them. - -Version 1.6.17rc06 [March 23, 2015] - Remove pnglibconf.dfn and pnglibconf.pre with "make clean". - Reformatted some "&0xff" instances to "& 0xff". - Fixed simplified 8-bit-linear to sRGB alpha. The calculated alpha - value was wrong. It's not clear if this affected the final stored - value; in the obvious code path the upper and lower 8-bits of the - alpha value were identical and the alpha was truncated to 8-bits - rather than dividing by 257 (John Bowler). - -Version 1.6.17 [March 26, 2015] - No changes. - -Version 1.6.18beta01 [April 1, 2015] - Removed PNG_SET_CHUNK_[CACHE|MALLOC]_LIMIT_SUPPORTED macros. They - have been combined with PNG_SET_USER_LIMITS_SUPPORTED (resolves - bug report by Andrew Church). - Fixed rgb_to_gray checks and added tRNS checks to pngvalid.c. This - fixes some arithmetic errors that caused some tests to fail on - some 32-bit platforms (Bug reports by Peter Breitenlohner [i686] - and Petr Gajdos [i586]). - -Version 1.6.18beta02 [April 26, 2015] - Suppressed some warnings from the Borland C++ 5.5.1/5.82 compiler - (Bug report by Viktor Szakats). - -Version 1.6.18beta03 [May 6, 2015] - Replaced "unexpected" with an integer (0xabadca11) in pngset.c - where a long was expected, to avoid a compiler warning when PNG_DEBUG > 1. - Added contrib/examples/simpleover.c, to demonstrate how to handle - alpha compositing of multiple images, using the "simplified API" - and an example PNG generation tool, contrib/examples/genpng.c - (John Bowler). - -Version 1.6.18beta04 [May 20, 2015] - PNG_RELEASE_BUILD replaces tests where the code depended on the build base - type and can be defined on the command line, allowing testing in beta - builds (John Bowler). - Avoid Coverity issue 80858 (REVERSE NULL) in pngtest.c PNG_DEBUG builds. - Avoid a harmless potential integer overflow in png_XYZ_from_xy() (Bug - report from Christopher Ferris). - -Version 1.6.18beta05 [May 31, 2015] - Backport filter selection code from libpng-1.7.0beta51, to combine - sub_row, up_row, avg_row, and paeth_row into try_row and tst_row. - Changed png_voidcast(), etc., to voidcast(), etc., in contrib/tools/pngfix.c - to avoid confusion with the libpng private macros. - Fixed old cut&paste bug in the weighted filter selection code in - pngwutil.c, introduced in libpng-0.95, March 1997. - -Version 1.6.18beta06 [June 1, 2015] - Removed WRITE_WEIGHTED_FILTERED code, to save a few kbytes of the - compiled library size. It never worked properly and as far as we can - tell, no one uses it. The png_set_filter_heuristics() and - png_set_filter_heuristics_fixed() APIs are retained but deprecated - and do nothing. - -Version 1.6.18beta07 [June 6, 2015] - Removed non-working progressive reader 'skip' function. This - function has apparently never been used. It was implemented - to support back-door modification of png_struct in libpng-1.4.x - but (because it does nothing and cannot do anything) was apparently - never tested (John Bowler). - Fixed cexcept.h in which GCC 5 now reports that one of the auto - variables in the Try macro needs to be volatile to prevent value - being lost over the setjmp (John Bowler). - Fixed NO_WRITE_FILTER and -Wconversion build breaks (John Bowler). - Fix g++ build breaks (John Bowler). - Quieted some Coverity issues in pngfix.c, png-fix-itxt.c, pngvalid.c, - pngstest.c, and pngimage.c. Most seem harmless, but png-fix-itxt - would only work with iTXt chunks with length 255 or less. - Added #ifdef's to contrib/examples programs so people don't try - to compile them without the minimum required support enabled - (suggested by Flavio Medeiros). - -Version 1.6.18beta08 [June 30, 2015] - Eliminated the final two Coverity defects (insecure temporary file - handling in contrib/libtests/pngstest.c; possible overflow of - unsigned char in contrib/tools/png-fix-itxt.c). To use the "secure" - file handling, define PNG_USE_MKSTEMP, otherwise "tmpfile()" will - be used. - Removed some unused WEIGHTED_FILTER macros from png.h and pngstruct.h - -Version 1.6.18beta09 [July 5, 2015] - Removed some useless typecasts from contrib/tools/png-fix-itxt.c - Fixed a new signed-unsigned comparison in pngrtran.c (Max Stepin). - Replaced arbitrary use of 'extern' with #define PNG_LINKAGE_*. To - preserve API compatibility, the new defines all default to "extern" - (requested by Jan Nijtmans). - -Version 1.6.18rc01 [July 9, 2015] - Belatedly added Mans Rullgard and James Yu to the list of Contributing - Authors. - -Version 1.6.18rc02 [July 12, 2015] - Restored unused FILTER_HEURISTIC macros removed at libpng-1.6.18beta08 - to png.h to avoid compatibility warnings. - -Version 1.6.18rc03 [July 15, 2015] - Minor changes to the man page - -Version 1.6.18 [July 23, 2015] - No changes. - -Version 1.6.19beta01 [July 30, 2015] - Updated obsolete information about the simplified API macros in the - manual pages (Bug report by Arc Riley). - Avoid potentially dereferencing NULL info_ptr in png_info_init_3(). - Rearranged png.h to put the major sections in the same order as - in libpng17. - Eliminated unused PNG_COST_SHIFT, PNG_WEIGHT_SHIFT, PNG_COST_FACTOR, and - PNG_WEIGHT_FACTOR macros. - Suppressed some warnings from the Borland C++ 5.5.1/5.82 compiler - (Bug report by Viktor Szakats). Several warnings remain and are - unavoidable, where we test for overflow. - Fixed potential leak of png_pixels in contrib/pngminus/pnm2png.c - Fixed uninitialized variable in contrib/gregbook/rpng2-x.c - -Version 1.6.19beta02 [August 19, 2015] - Moved config.h.in~ from the "libpng_autotools_files" list to the - "libpng_autotools_extra" list in autogen.sh because it was causing a - false positive for missing files (bug report by Robert C. Seacord). - Removed unreachable "break" statements in png.c, pngread.c, and pngrtran.c - to suppress clang warnings (Bug report by Viktor Szakats). - Fixed some bad links in the man page. - Changed "n bit" to "n-bit" in comments. - Added signed/unsigned 16-bit safety net. This removes the dubious - 0x8000 flag definitions on 16-bit systems. They aren't supported - yet the defs *probably* work, however it seems much safer to do this - and be advised if anyone, contrary to advice, is building libpng 1.6 - on a 16-bit system. It also adds back various switch default clauses - for GCC; GCC errors out if they are not present (with an appropriately - high level of warnings). - Safely convert num_bytes to a png_byte in png_set_sig_bytes() (Robert - Seacord). - Fixed the recently reported 1's complement security issue by replacing - the value that is illegal in the PNG spec, in both signed and unsigned - values, with 0. Illegal unsigned values (anything greater than or equal - to 0x80000000) can still pass through, but since these are not illegal - in ANSI-C (unlike 0x80000000 in the signed case) the checking that - occurs later can catch them (John Bowler). - -Version 1.6.19beta03 [September 26, 2015] - Fixed png_save_int_32 when int is not 2's complement (John Bowler). - Updated libpng16 with all the recent test changes from libpng17, - including changes to pngvalid.c to ensure that the original, - distributed, version of contrib/visupng/cexcept.h can be used - (John Bowler). - pngvalid contains the correction to the use of SAVE/STORE_ - UNKNOWN_CHUNKS; a bug revealed by changes in libpng 1.7. More - tests contain the --strict option to detect warnings and the - pngvalid-standard test has been corrected so that it does not - turn on progressive-read. There is a separate test which does - that. (John Bowler) - Also made some signed/unsigned fixes. - Make pngstest error limits version specific. Splitting the machine - generated error structs out to a file allows the values to be updated - without changing pngstest.c itself. Since libpng 1.6 and 1.7 have - slightly different error limits this simplifies maintenance. The - makepngs.sh script has also been updated to more accurately reflect - current problems in libpng 1.7 (John Bowler). - Incorporated new test PNG files into make check. tests/pngstest-* - are changed so that the new test files are divided into 8 groups by - gamma and alpha channel. These tests have considerably better code - and pixel-value coverage than contrib/pngsuite; however,coverage is - still incomplete (John Bowler). - Removed the '--strict' in 1.6 because of the double-gamma-correction - warning, updated pngstest-errors.h for the errors detected with the - new contrib/testspngs PNG test files (John Bowler). - -Version 1.6.19beta04 [October 15, 2015] - Worked around rgb-to-gray issues in libpng 1.6. The previous - attempts to ignore the errors in the code aren't quite enough to - deal with the 'channel selection' encoding added to libpng 1.7; abort. - pngvalid.c is changed to drop this encoding in prior versions. - Fixed 'pow' macros in pngvalid.c. It is legal for 'pow' to be a - macro, therefore the argument list cannot contain preprocessing - directives. Make sure pow is a function where this happens. This is - a minimal safe fix, the issue only arises in non-performance-critical - code (bug report by Curtis Leach, fix by John Bowler). - Added sPLT support to pngtest.c - -Version 1.6.19rc01 [October 23, 2015] - No changes. - -Version 1.6.19rc02 [October 31, 2015] - Prevent setting or writing over-length PLTE chunk (Cosmin Truta). - Silently truncate over-length PLTE chunk while reading. - Libpng incorrectly calculated the output rowbytes when the application - decreased either the number of channels or the bit depth (or both) in - a user transform. This was safe; libpng overallocated buffer space - (potentially by quite a lot; up to 4 times the amount required) but, - from 1.5.4 on, resulted in a png_error (John Bowler). - -Version 1.6.19rc03 [November 3, 2015] - Fixed some inconsequential cut-and-paste typos in png_set_cHRM_XYZ_fixed(). - Clarified COPYRIGHT information to state explicitly that versions - are derived from previous versions. - Removed much of the long list of previous versions from png.h and - libpng.3. - -Version 1.6.19rc04 [November 5, 2015] - Fixed new bug with CRC error after reading an over-length palette - (bug report by Cosmin Truta) (CVE-2015-8126). - -Version 1.6.19 [November 12, 2015] - Cleaned up coding style in png_handle_PLTE(). - -Version 1.6.20beta01 [November 20, 2015] - Avoid potential pointer overflow/underflow in png_handle_sPLT() and - png_handle_pCAL() (Bug report by John Regehr). - -Version 1.6.20beta02 [November 23, 2015] - Fixed incorrect implementation of png_set_PLTE() that uses png_ptr - not info_ptr, that left png_set_PLTE() open to the CVE-2015-8126 - vulnerability. Fixes CVE-2015-8472. - -Version 1.6.20beta03 [November 24, 2015] - Backported tests from libpng-1.7.0beta69. - -Version 1.6.20rc01 [November 26, 2015] - Fixed an error in handling of bad zlib CMINFO field in pngfix, found by - American Fuzzy Lop, reported by Brian Carpenter. inflate() doesn't - immediately fault a bad CMINFO field; instead a 'too far back' error - happens later (at least some times). pngfix failed to limit CMINFO to - the allowed values but then assumed that window_bits was in range, - triggering an assert. The bug is mostly harmless; the PNG file cannot - be fixed. - -Version 1.6.20rc02 [November 29, 2015] - In libpng 1.6 zlib initialization was changed to use the window size - in the zlib stream, not a fixed value. This causes some invalid images, - where CINFO is too large, to display 'correctly' if the rest of the - data is valid. This provides a workaround for zlib versions where the - error arises (ones that support the API change to use the window size - in the stream). - -Version 1.6.20 [December 3, 2015] - No changes. - -Version 1.6.21beta01 [December 11, 2015] - Fixed syntax "$(command)" in tests/pngstest that some shells other than - bash could not parse (Bug report by Nelson Beebe). Use `command` instead. - -Version 1.6.21beta02 [December 14, 2015] - Moved png_check_keyword() from pngwutil.c to pngset.c - Removed LE/BE dependencies in pngvalid, to 'fix' the current problem - in the BigEndian tests by not testing it, making the BE code the same - as the LE version. - Fixes to pngvalid for various reduced build configurations (eliminate unused - statics) and a fix for the case in rgb_to_gray when the digitize option - reduces graylo to 0, producing a large error. - -Version 1.6.21beta03 [December 18, 2015] - Widened the 'limit' check on the internally calculated error limits in - the 'DIGITIZE' case (the code used prior to 1.7 for rgb_to_gray error - checks) and changed the check to only operate in non-release builds - (base build type not RC or RELEASE.) - Fixed undefined behavior in pngvalid.c, undefined because - (png_byte) << shift is undefined if it changes the signed bit - (because png_byte is promoted to int). The libpng exported functions - png_get_uint_32 and png_get_uint_16 handle this. (Bug reported by - David Drysdale as a result of reports from UBSAN in clang 3.8). - This changes pngvalid to use BE random numbers; this used to produce - errors but these should not be fixed as a result of the previous changes. - -Version 1.6.21rc01 [January 4, 2016] - In projects/vstudio, combined readme.txt and WARNING into README.txt - -Version 1.6.21rc02 [January 7, 2016] - Relocated assert() in contrib/tools/pngfix.c, bug found by American - Fuzzy Lop, reported by Brian Carpenter. - Marked 'limit' UNUSED in transform_range_check(). This only affects - release builds. - -Version 1.6.21 [January 15, 2016] - Worked around a false-positive Coverity issue in pngvalid.c. - -Version 1.6.22beta01 [January 23, 2016] - Changed PNG_USE_MKSTEMP to __COVERITY__ to select alternate - "tmpfile()" implementation in contrib/libtests/pngstest.c - Fixed NO_STDIO build of pngunknown.c to skip calling png_init_io() - if there is no stdio.h support. - Added a png_image_write_to_memory() API and a number of assist macros - to allow an application that uses the simplified API write to bypass - stdio and write directly to memory. - Added some warnings (png.h) and some check code to detect *possible* - overflow in the ROW_STRIDE and simplified image SIZE macros. This - disallows image width/height/format that *might* overflow. This is - a quiet API change that limits in-memory image size (uncompressed) to - less than 4GByte and image row size (stride) to less than 2GByte. - Revised workaround for false-positive Coverity issue in pngvalid.c. - -Version 1.6.22beta02 [February 8, 2016] - Only use exit(77) in configure builds. - Corrected error in PNG_IMAGE_PNG_SIZE_MAX. This new macro underreported - the palette size because it failed to take into account that the memory - palette has to be expanded to full RGB when it is written to PNG. - Updated CMakeLists.txt, added supporting scripts/gen*.cmake.in - and test.cmake.in (Roger Leigh). - Relaxed limit checks on gamma values in pngrtran.c. As suggested in - the comments gamma values outside the range currently permitted - by png_set_alpha_mode are useful for HDR data encoding. These values - are already permitted by png_set_gamma so it is reasonable caution to - extend the png_set_alpha_mode range as HDR imaging systems are starting - to emerge. - -Version 1.6.22beta03 [March 9, 2016] - Added a common-law trademark notice and export control information - to the LICENSE file, png.h, and the man page. - Restored "& 0xff" in png_save_uint_16() and png_save_uint_32() that - were accidentally removed from libpng-1.6.17. - Changed PNG_INFO_cHNK and PNG_FREE_cHNK from 0xnnnn to 0xnnnnU in png.h - (Robert C. Seacord). - Removed dubious "#if INT_MAX" test from png.h that was added to - libpng-1.6.19beta02 (John Bowler). - Add ${INCLUDES} in scripts/genout.cmake.in (Bug report by Nixon Kwok). - Updated LICENSE to say files in the contrib directory are not - necessarily under the libpng license, and that some makefiles have - other copyright owners. - Added INTEL-SSE2 support (Mike Klein and Matt Sarett, Google, Inc.). - Made contrib/libtests/timepng more robust. The code no longer gives - up/fails on invalid PNG data, it just skips it (with error messages). - The code no longer fails on PNG files with data beyond IEND. Options - exist to use png_read_png (reading the whole image, not by row) and, in - that case, to apply any of the supported transforms. This makes for - more realistic testing; the decoded data actually gets used in a - meaningful fashion (John Bowler). - Fixed some misleading indentation (Krishnaraj Bhat). - -Version 1.6.22beta04 [April 5, 2016] - Force GCC compilation to C89 if needed (Dagobert Michelsen). - SSE filter speed improvements for bpp=3: - memcpy-free implementations of load3() / store3(). - call load3() only when needed at the end of a scanline. - -Version 1.6.22beta05 [April 27, 2016] - Added PNG_FAST_FILTERS macro (defined as - PNG_FILTER_NONE|PNG_FILTER_SUB|PNG_FILTER_UP). - Various fixes for contrib/libtests/timepng.c - Moved INTEL-SSE code from pngpriv.h into contrib/intel/intel_sse.patch. - Fixed typo (missing underscore) in #define PNG_READ_16_TO_8_SUPPORTED - (Bug report by Y.Ohashik). - -Version 1.6.22beta06 [May 5, 2016] - Rebased contrib/intel_sse.patch. - Quieted two Coverity issues in contrib/libtests/timepng.c. - Fixed issues with scripts/genout.cmake.in (David Capello, Nixon Kwok): - Added support to use multiple directories in ZLIBINCDIR variable, - Fixed CMAKE_C_FLAGS with multiple values when genout is compiled on MSVC, - Fixed pnglibconf.c compilation on OS X including the sysroot path. - -Version 1.6.22rc01 [May 14, 2016] - No changes. - -Version 1.6.22rc02 [May 16, 2016] - Removed contrib/timepng from default build; it does not build on platforms - that don't supply clock_gettime(). - -Version 1.6.22rc03 [May 17, 2016] - Restored contrib/timepng to default build but check for the presence - of clock_gettime() in configure.ac and Makefile.am. - -Version 1.6.22 [May 26, 2016] - No changes. - -Version 1.6.23beta01 [May 29, 2016] - Stop a potential memory leak in png_set_tRNS() (Bug report by Ted Ying). - Fixed the progressive reader to handle empty first IDAT chunk properly - (patch by Timothy Nikkel). This bug was introduced in libpng-1.6.0 and - only affected the libpng16 branch. - Added tests in pngvalid.c to check zero-length IDAT chunks in various - positions. Fixed the sequential reader to handle these more robustly - (John Bowler). - -Version 1.6.23rc01 [June 2, 2016] - Corrected progressive read input buffer in pngvalid.c. The previous version - the code invariably passed just one byte at a time to libpng. The intent - was to pass a random number of bytes in the range 0..511. - Moved sse2 prototype from pngpriv.h to contrib/intel/intel_sse.patch. - Added missing ")" in pngerror.c (Matt Sarrett). - -Version 1.6.23rc02 [June 4, 2016] - Fixed undefined behavior in png_push_save_buffer(). Do not call - memcpy() with a null source, even if count is zero (Leon Scroggins III). - -Version 1.6.23 [June 9, 2016] - Fixed bad link to RFC2083 in png.5 (Nikola Forro). - -Version 1.6.24beta01 [June 11, 2016] - Avoid potential overflow of the PNG_IMAGE_SIZE macro. This macro - is not used within libpng, but is used in some of the examples. - -Version 1.6.24beta02 [June 23, 2016] - Correct filter heuristic overflow handling. This was broken when the - write filter code was moved out-of-line; if there is a single filter and - the heuristic sum overflows the calculation of the filtered line is not - completed. In versions prior to 1.6 the code was duplicated in-line - and the check not performed, so the filter operation completed; however, - in the multi-filter case where the sum is performed the 'none' filter would - be selected if all the sums overflowed, even if it wasn't in the filter - list. The fix to the first problem is simply to provide PNG_SIZE_MAX as - the current lmins sum value; this means the sum can never exceed it and - overflows silently. A reasonable compiler that does choose to inline - the code will simply eliminate the sum check. - The fix to the second problem is to use high precision arithmetic (this is - implemented in 1.7), however a simple safe fix here is to chose the lowest - numbered filter in the list from png_set_filter (this only works if the - first problem is also fixed) (John Bowler). - Use a more efficient absolute value calculation on SSE2 (Matthieu Darbois). - Fixed the case where PNG_IMAGE_BUFFER_SIZE can overflow in the application - as a result of the application using an increased 'row_stride'; previously - png_image_finish_read only checked for overflow on the base calculation of - components. (I.e. it checked for overflow of a 32-bit number on the total - number of pixel components in the output format, not the possibly padded row - length and not the number of bytes, which for linear formats is twice the - number of components.) - MSVC does not like '-(unsigned)', so replaced it with 0U-(unsigned) - MSVC does not like (uInt) = -(unsigned) (i.e. as an initializer), unless - the conversion is explicitly invoked by a cast. - Put the SKIP definition in the correct place. It needs to come after the - png.h include (see all the other .c files in contrib/libtests) because it - depends on PNG_LIBPNG_VER. - Removed the three compile warning options from the individual project - files into the zlib.props globals. It increases the warning level from 4 - to All and adds a list of the warnings that need to be turned off. This is - semi-documentary; the intent is to tell libpng users which warnings have - been examined and judged non-fixable at present. The warning about - structure padding is fixable, but it would be a signficant change (moving - structure members around). - -Version 1.6.24beta03 [July 4, 2016] - Optimized absolute value calculation in filter selection, similar to - code in the PAETH decoder in pngrutil.c. Build with PNG_USE_ABS to - use this. - Added pngcp to the build together with a pngcp.dfa configuration test. - Added high resolution timing to pngcp. - Added "Common linking failures" section to INSTALL. - Relocated misplaced #endif in png.c sRGB profile checking. - Fixed two Coverity issues in pngcp.c. - -Version 1.6.24beta04 [July 8, 2016] - Avoid filter-selection heuristic sum calculations in cases where only one - filter is a candidate for selection. This trades off code size (added - private png_setup_*_row_only() functions) for speed. - -Version 1.6.24beta05 [July 13, 2016] - Fixed some indentation to comply with our coding style. - Added contrib/tools/reindent. - -Version 1.6.24beta06 [July 18, 2016] - Fixed more indentation to comply with our coding style. - Eliminated unnecessary tests of boolean png_isaligned() vs 0. - -Version 1.6.24rc01 [July 25, 2016] - No changes. - -Version 1.6.24rc02 [August 1, 2016] - Conditionally compile SSE2 headers in contrib/intel/intel_sse.patch - Conditionally compile png_decompress_chunk(). - -Version 1.6.24rc03 [August 2, 2016] - Conditionally compile ARM_NEON headers in pngpriv.h - Updated contrib/intel/intel_sse.patch - -Version 1.6.24[August 4, 2016] - No changes. - -Version 1.6.25beta01 [August 12, 2016] - Reject oversized iCCP profile immediately. - Cleaned up PNG_DEBUG compile of pngtest.c. - Conditionally compile png_inflate(). - -Version 1.6.25beta02 [August 18, 2016] - Don't install pngcp; it conflicts with pngcp in the pngtools package. - Minor editing of INSTALL, (whitespace, added copyright line) - -Version 1.6.25rc01 [August 24, 2016] - No changes. - -Version 1.6.25rc02 [August 29, 2016] - Added MIPS support (Mandar Sahastrabuddhe ). - Only the UP filter is currently implemented. - -Version 1.6.25rc03 [August 29, 2016] - Rebased contrib/intel/intel_sse.patch after the MIPS implementation. - -Version 1.6.25rc04 [August 30, 2016] - Added MIPS support for SUB, AVG, and PAETH filters (Mandar Sahastrabuddhe). - -Version 1.6.25rc05 [August 30, 2016] - Rebased contrib/intel/intel_sse.patch after the MIPS implementation update.. - -Version 1.6.25 [September 1, 2016] - No changes. - -Version 1.6.26beta01 [September 26, 2016] - Fixed handling zero length IDAT in pngfix (bug report by Agostino Sarubbo, - bugfix by John Bowler). - Do not issue a png_error() on read in png_set_pCAL() because png_handle_pCAL - has allocated memory that libpng needs to free. - Conditionally compile png_set_benign_errors() in pngread.c and pngtest.c - Issue a png_benign_error instead of a png_error on ADLER32 mismatch - while decoding compressed data chunks. - Changed PNG_ZLIB_VERNUM to ZLIB_VERNUM in pngpriv.h, pngstruct.h, and - pngrutil.c. - If CRC handling of critical chunks has been set to PNG_CRC_QUIET_USE, - ignore the ADLER32 checksum in the IDAT chunk as well as the chunk CRCs. - Issue png_benign_error() on ADLER32 checksum mismatch instead of png_error(). - Add tests/badcrc.png and tests/badadler.png to tests/pngtest. - Merged pngtest.c with libpng-1.7.0beta84/pngtest.c - -Version 1.6.26beta02 [October 1, 2016] - Updated the documentation about CRC and ADLER32 handling. - Quieted 117 warnings from clang-3.8 in pngtrans.c, pngread.c, - pngwrite.c, pngunknown.c, and pngvalid.c. - Quieted 58 (out of 144) -Wconversion compiler warnings by changing - flag definitions in pngpriv.h from 0xnnnn to 0xnnnnU and trivial changes - in png.c, pngread.c, and pngwutil.c. - -Version 1.6.26beta03 [October 2, 2016] - Removed contrib/libtests/*.orig and *.rej that slipped into the tarballs. - Quieted the 86 remaining -Wconversion compiler warnings by - revising the png_isaligned() macro and trivial changes in png.c, - pngerror.c, pngget.c, pngmem.c, pngset.c, pngrtran.c, pngrutil.c, - pngwtran.c, pngwrite.c, and pngwutil.c. - -Version 1.6.26beta04 [October 3, 2016] - Quieted (bogus?) clang warnings about "absolute value has no effect" - when PNG_USE_ABS is defined. - Fixed offsets in contrib/intel/intel_sse.patch - -Version 1.6.26beta05 [October 6, 2016] - Changed integer constant 4294967294 to unsigned 4294967294U in pngconf.h - to avoid a signed/unsigned compare in the preprocessor. - -Version 1.6.26beta06 [October 7, 2016] - Use zlib-1.2.8.1 inflateValidate() instead of inflateReset2() to - optionally avoid ADLER32 evaluation. - -Version 1.6.26rc01 [October 12, 2016] - No changes. - -Version 1.6.26 [October 20, 2016] - Cosmetic change, "ptr != 0" to "ptr != NULL" in png.c and pngrutil.c - Despammed email addresses (replaced "@" with " at "). - -Version 1.6.27beta01 [November 2, 2016] - Restrict the new ADLER32-skipping to IDAT chunks. It broke iCCP chunk - handling: an erroneous iCCP chunk would throw a png_error and reject the - entire PNG image instead of rejecting just the iCCP chunk with a warning, - if built with zlib-1.2.8.1. - -Version 1.6.27rc01 [December 27, 2016] - Control ADLER32 checking with new PNG_IGNORE_ADLER32 option. Fixes - an endless loop when handling erroneous ADLER32 checksums; bug - introduced in libpng-1.6.26. - Removed the use of a macro containing the pre-processor 'defined' - operator. It is unclear whether this is valid; a macro that - "generates" 'defined' is not permitted, but the use of the word - "generates" within the C90 standard seems to imply more than simple - substitution of an expression itself containing a well-formed defined - operation. - Added ARM support to CMakeLists.txt (Andreas Franek). - -Version 1.6.27 [December 29, 2016] - Fixed a potential null pointer dereference in png_set_text_2() (bug report - and patch by Patrick Keshishian, CVE-2016-10087). - -Version 1.6.28rc01 [January 3, 2017] - Fixed arm/aarch64 detection in CMakeLists.txt (Gianfranco Costamagna). - Added option to Cmake build allowing a custom location of zlib to be - specified in a scenario where libpng is being built as a subproject - alongside zlib by another project (Sam Serrels). - Changed png_ptr->options from a png_byte to png_uint_32, to accomodate - up to 16 options. - -Version 1.6.28rc02 [January 4, 2017] - Added "include(GNUInstallDirs)" to CMakeLists.txt (Gianfranco Costamagna). - Moved SSE2 optimization code into the main libpng source directory. - Configure libpng with "configure --enable-intel-sse" or compile - libpng with "-DPNG_INTEL_SSE" in CPPFLAGS to enable it. - -Version 1.6.28rc03 [January 4, 2017] - Backed out the SSE optimization and last CMakeLists.txt to allow time for QA. - -Version 1.6.28 [January 5, 2017] - No changes. - -Version 1.6.29beta01 [January 12, 2017] - Readded "include(GNUInstallDirs)" to CMakeLists.txt (Gianfranco Costamagna). - Moved SSE2 optimization code into the main libpng source directory. - Configure libpng with "configure --enable-intel-sse" or compile - libpng with "-DPNG_INTEL_SSE" in CPPFLAGS to enable it. - Simplified conditional compilation in pngvalid.c, for AIX (Michael Felt). - -Version 1.6.29beta02 [February 22, 2017] - Avoid conditional directives that break statements in pngrutil.c (Romero - Malaquias) - The contrib/examples/pngtopng.c recovery code was in the wrong "if" - branches; the comments were correct. - Added code for PowerPC VSX optimisation (Vadim Barkov). - -Version 1.6.29beta03 [March 1, 2017] - Avoid potential overflow of shift operations in png_do_expand() (Aaron Boxer). - Change test ZLIB_VERNUM >= 0x1281 to ZLIB_VERNUM >= 0x1290 in pngrutil.c - because Solaris 11 distributes zlib-1.2.8.f that is older than 1.2.8.1, - as suggested in zlib FAQ, item 24. - Suppress clang warnings about implicit sign changes in png.c - -Version 1.6.29 [March 16, 2017] - No changes. - -Version 1.6.30beta01 [April 1, 2017] - Added missing "$(CPPFLAGS)" to the compile line for c.pic.o in - makefile.linux and makefile.solaris-x86 (Cosmin). - Revised documentation of png_get_error_ptr() in the libpng manual. - Silence clang -Wcomma and const drop warnings (Viktor Szakats). - Update Sourceforge URLs in documentation (https instead of http). - -Version 1.6.30beta02 [April 22, 2017] - Document need to check for integer overflow when allocating a pixel - buffer for multiple rows in contrib/gregbook, contrib/pngminus, - example.c, and in the manual (suggested by Jaeseung Choi). This - is similar to the bug reported against pngquant in CVE-2016-5735. - Removed reference to the obsolete PNG_SAFE_LIMITS macro in the documentation. - -Version 1.6.30beta03 [May 22, 2017] - Check for integer overflow in contrib/visupng and contrib/tools/genpng. - Do not double evaluate CMAKE_SYSTEM_PROCESSOR in CMakeLists.txt. - Test CMAKE_HOST_WIN32 instead of WIN32 in CMakeLists.txt. - Fix some URL in documentation. - -Version 1.6.30beta04 [June 7, 2017] - Avoid writing an empty IDAT when the last IDAT exactly fills the - compression buffer (bug report by Brian Baird). This bug was - introduced in libpng-1.6.0. - -Version 1.6.30rc01 [June 14, 2017] - No changes. - -Version 1.6.30rc02 [June 25, 2017] - Update copyright year in pnglibconf.h, make ltmain.sh executable. - Add a reference to the libpng.download site in README. - -Version 1.6.30 [June 28, 2017] - No changes. - -Version 1.6.31beta01 [July 5, 2017] - Guard the definition of _POSIX_SOURCE in pngpriv.h (AIX already defines it; - bug report by Michael Felt). - Revised pngpriv.h to work around failure to compile arm/filter_neon.S - ("typedef" directive is unrecognized by the assembler). The problem - was introduced in libpng-1.6.30beta01. - Added "Requires: zlib" to libpng.pc.in (Pieter Neerincx). - Added special case for FreeBSD in arm/filter_neon.S (Maya Rashish). - -Version 1.6.31beta02 [July 8, 2017] - Added instructions for disabling hardware optimizations in INSTALL. - Added "--enable-hardware-optimizations" configuration flag to enable - or disable all hardware optimizations with one flag. - -Version 1.6.31beta03 [July 9, 2017] - Updated CMakeLists.txt to add INTEL_SSE and MIPS_MSA platforms. - Changed "int" to "png_size_t" in intel/filter_sse2.c to prevent - possible integer overflow (Bug report by John Bowler). - Quieted "declaration after statement" warnings in intel/filter_sse2.c. - Added scripts/makefile-linux-opt, which has hardware optimizations enabled. - -Version 1.6.31beta04 [July 11, 2017] - Removed one of the GCC-7.1.0 'strict-overflow' warnings that result when - integers appear on both sides of a compare. Worked around the others by - forcing the strict-overflow setting in the relevant functions to a level - where they are not reported (John Bowler). - Changed "FALL THROUGH" comments to "FALLTHROUGH" because GCC doesn't like - the space. - Worked around some C-style casts from (void*) because g++ 5.4.0 objects - to them. - Increased the buffer size for 'sprint' to pass the gcc 7.1.0 'sprint - overflow' check that is on by default with -Wall -Wextra. - -Version 1.6.31beta05 [July 13, 2017] - Added eXIf chunk support. - -Version 1.6.31beta06 [July 17, 2017] - Added a minimal eXIf chunk (with Orientation and FocalLengthIn35mmFilm - tags) to pngtest.png. - -Version 1.6.31beta07 [July 18, 2017] - Revised the eXIf chunk in pngtest.png to fix "Bad IFD1 Directory" warning. - -Version 1.6.31rc01 [July 19, 2017] - No changes. - -Version 1.6.31rc02 [July 25, 2017] - Fixed typo in example.c (png_free_image should be png_image_free) (Bug - report by John Smith) - -Version 1.6.31 [July 27, 2017] - No changes. - -Version 1.6.32beta01 [July 31, 2017] - Avoid possible NULL dereference in png_handle_eXIf when benign_errors - are allowed. Avoid leaking the input buffer "eXIf_buf". - Eliminated png_ptr->num_exif member from pngstruct.h and added num_exif - to arguments for png_get_eXIf() and png_set_eXIf(). - Added calls to png_handle_eXIf(() in pngread.c and png_write_eXIf() in - pngwrite.c, and made various other fixes to png_write_eXIf(). - Changed name of png_get_eXIF and png_set_eXIf() to png_get_eXIf_1() and - png_set_eXIf_1(), respectively, to avoid breaking API compatibility - with libpng-1.6.31. - -Version 1.6.32beta02 [August 1, 2017] - Updated contrib/libtests/pngunknown.c with eXIf chunk. - -Version 1.6.32beta03 [August 2, 2017] - Initialized btoa[] in pngstest.c - Stop memory leak when returning from png_handle_eXIf() with an error - (Bug report from the OSS-fuzz project). - -Version 1.6.32beta04 [August 2, 2017] - Replaced local eXIf_buf with info_ptr-eXIf_buf in png_handle_eXIf(). - Update libpng.3 and libpng-manual.txt about eXIf functions. - -Version 1.6.32beta05 [August 2, 2017] - Restored png_get_eXIf() and png_set_eXIf() to maintain API compatability. - -Version 1.6.32beta06 [August 2, 2017] - Removed png_get_eXIf_1() and png_set_eXIf_1(). - -Version 1.6.32beta07 [August 3, 2017] - Check length of all chunks except IDAT against user limit to fix an - OSS-fuzz issue (Fixes CVE-2017-12652). - -Version 1.6.32beta08 [August 3, 2017] - Check length of IDAT against maximum possible IDAT size, accounting - for height, rowbytes, interlacing and zlib/deflate overhead. - Restored png_get_eXIf_1() and png_set_eXIf_1(), because strlen(eXIf_buf) - does not work (the eXIf chunk data can contain zeroes). - -Version 1.6.32beta09 [August 3, 2017] - Require cmake-2.8.8 in CMakeLists.txt. Revised symlink creation, - no longer using deprecated cmake LOCATION feature (Clifford Yapp). - Fixed five-byte error in the calculation of IDAT maximum possible size. - -Version 1.6.32beta10 [August 5, 2017] - Moved chunk-length check into a png_check_chunk_length() private - function (Suggested by Max Stepin). - Moved bad pngs from tests to contrib/libtests/crashers - Moved testing of bad pngs into a separate tests/pngtest-badpngs script - Added the --xfail (expected FAIL) option to pngtest.c. It writes XFAIL - in the output but PASS for the libpng test. - Require cmake-3.0.2 in CMakeLists.txt (Clifford Yapp). - Fix "const" declaration info_ptr argument to png_get_eXIf_1() and the - num_exif argument to png_get_eXIf_1() (Github Issue 171). - -Version 1.6.32beta11 [August 7, 2017] - Added "eXIf" to "chunks_to_ignore[]" in png_set_keep_unknown_chunks(). - Added huge_IDAT.png and empty_ancillary_chunks.png to testpngs/crashers. - Make pngtest --strict, --relax, --xfail options imply -m (multiple). - Removed unused chunk_name parameter from png_check_chunk_length(). - Relocated setting free_me for eXIf data, to stop an OSS-fuzz leak. - Initialize profile_header[] in png_handle_iCCP() to fix OSS-fuzz issue. - Initialize png_ptr->row_buf[0] to 255 in png_read_row() to fix OSS-fuzz UMR. - Attempt to fix a UMR in png_set_text_2() to fix OSS-fuzz issue. - Increase minimum zlib stream from 9 to 14 in png_handle_iCCP(), to account - for the minimum 'deflate' stream, and relocate the test to a point - after the keyword has been read. - Check that the eXIf chunk has at least 2 bytes and begins with "II" or "MM". - -Version 1.6.32rc01 [August 18, 2017] - Added a set of "huge_xxxx_chunk.png" files to contrib/testpngs/crashers, - one for each known chunk type, with length = 2GB-1. - Check for 0 return from png_get_rowbytes() and added some (size_t) typecasts - in contrib/pngminus/*.c to stop some Coverity issues (162705, 162706, - and 162707). - Renamed chunks in contrib/testpngs/crashers to avoid having files whose - names differ only in case; this causes problems with some platforms - (github issue #172). - -Version 1.6.32rc02 [August 22, 2017] - Added contrib/oss-fuzz directory which contains files used by the oss-fuzz - project (https://github.com/google/oss-fuzz/tree/master/projects/libpng). - -Version 1.6.32 [August 24, 2017] - No changes. - -Version 1.6.33beta01 [August 28, 2017] - Added PNGMINUS_UNUSED macro to contrib/pngminus/p*.c and added missing - parenthesis in contrib/pngminus/pnm2png.c (bug report by Christian Hesse). - Fixed off-by-one error in png_do_check_palette_indexes() (Bug report - by Mick P., Source Forge Issue #269). - -Version 1.6.33beta02 [September 3, 2017] - Initialize png_handler.row_ptr in contrib/oss-fuzz/libpng_read_fuzzer.cc - to fix shortlived oss-fuzz issue 3234. - Compute a larger limit on IDAT because some applications write a deflate - buffer for each row (Bug report by Andrew Church). - Use current date (DATE) instead of release-date (RDATE) in last - changed date of contrib/oss-fuzz files. - Enabled ARM support in CMakeLists.txt (Bernd Kuhls). - -Version 1.6.33beta03 [September 14, 2017] - Fixed incorrect typecast of some arguments to png_malloc() and - png_calloc() that were png_uint_32 instead of png_alloc_size_t - (Bug report by "irwir" in Github libpng issue #175). - Use pnglibconf.h.prebuilt when building for ANDROID with cmake (Github - issue 162, by rcdailey). - -Version 1.6.33rc01 [September 20, 2017] - Initialize memory allocated by png_inflate to zero, using memset, to - stop an oss-fuzz "use of uninitialized value" detection in png_set_text_2() - due to truncated iTXt or zTXt chunk. - Initialize memory allocated by png_read_buffer to zero, using memset, to - stop an oss-fuzz "use of uninitialized value" detection in - png_icc_check_tag_table() due to truncated iCCP chunk. - Removed a redundant test (suggested by "irwir" in Github issue #180). - -Version 1.6.33rc02 [September 23, 2017] - Added an interlaced version of each file in contrib/pngsuite. - Relocate new memset() call in pngrutil.c. - Removed more redundant tests (suggested by "irwir" in Github issue #180). - Add support for loading images with associated alpha in the Simplified - API (Samuel Williams). - -Version 1.6.33 [September 28, 2017] - Revert contrib/oss-fuzz/libpng_read_fuzzer.cc to libpng-1.6.32 state. - Initialize png_handler.row_ptr in contrib/oss-fuzz/libpng_read_fuzzer.cc - Add end_info structure and png_read_end() to the libpng fuzzer. - -Version 1.6.34 [September 29, 2017] - Removed contrib/pngsuite/i*.png; some of these were incorrect and caused - test failures. - -Send comments/corrections/commendations to png-mng-implement at lists.sf.net -(subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-implement -to subscribe) -or to glennrp at users.sourceforge.net - -Glenn R-P -#endif diff --git a/libs/freeimage/src/LibPNG/INSTALL b/libs/freeimage/src/LibPNG/INSTALL deleted file mode 100644 index e8edb7240f..0000000000 --- a/libs/freeimage/src/LibPNG/INSTALL +++ /dev/null @@ -1,465 +0,0 @@ - - Installing libpng - -Contents - - I. Simple installation - II. Rebuilding the configure scripts - III. Using scripts/makefile* - IV. Using cmake - V. Directory structure - VI. Building with project files - VII. Building with makefiles - VIII. Configuring libpng for 16-bit platforms - IX. Configuring for DOS - X. Configuring for Medium Model - XI. Prepending a prefix to exported symbols - XII. Configuring for compiler xxx: - XIII. Removing unwanted object code - XIV. Enabling or disabling hardware optimizations - XV. Changes to the build and configuration of libpng in libpng-1.5.x - XVI. Setjmp/longjmp issues - XVII. Common linking failures - XVIII. Other sources of information about libpng - -I. Simple installation - -On Unix/Linux and similar systems, you can simply type - - ./configure [--prefix=/path] - make check - make install - -and ignore the rest of this document. "/path" is the path to the directory -where you want to install the libpng "lib", "include", and "bin" -subdirectories. - -If you downloaded a GIT clone, you will need to run ./autogen.sh before -running ./configure, to create "configure" and "Makefile.in" which are -not included in the GIT repository. - -Note that "configure" is only included in the "*.tar" distributions and not -in the "*.zip" or "*.7z" distributions. If you downloaded one of those -distributions, see "Building with project files" or "Building with makefiles", -below. - -II. Rebuilding the configure scripts - -If configure does not work on your system, or if you have a need to -change configure.ac or Makefile.am, and you have a reasonably -up-to-date set of tools, running ./autogen.sh in a git clone before -running ./configure may fix the problem. To be really sure that you -aren't using any of the included pre-built scripts, especially if you -are building from a tar distribution instead of a git distribution, -do this: - - ./configure --enable-maintainer-mode - make maintainer-clean - ./autogen.sh --maintainer --clean - ./autogen.sh --maintainer - ./configure [--prefix=/path] [other options] - make - make install - make check - -III. Using scripts/makefile* - -Instead, you can use one of the custom-built makefiles in the -"scripts" directory - - cp scripts/pnglibconf.h.prebuilt pnglibconf.h - cp scripts/makefile.system makefile - make test - make install - -The files that are presently available in the scripts directory -are listed and described in scripts/README.txt. - -Or you can use one of the "projects" in the "projects" directory. - -Before installing libpng, you must first install zlib, if it -is not already on your system. zlib can usually be found -wherever you got libpng; otherwise go to https://zlib.net/. You can -place zlib in the same directory as libpng or in another directory. - -If your system already has a preinstalled zlib you will still need -to have access to the zlib.h and zconf.h include files that -correspond to the version of zlib that's installed. - -If you wish to test with a particular zlib that is not first in the -standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS, -and LD_LIBRARY_PATH in your environment before running "make test" -or "make distcheck": - - ZLIBLIB=/path/to/lib export ZLIBLIB - ZLIBINC=/path/to/include export ZLIBINC - CPPFLAGS="-I$ZLIBINC" export CPPFLAGS - LDFLAGS="-L$ZLIBLIB" export LDFLAGS - LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH - -If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC -in your environment and type - - make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test - -IV. Using cmake - -If you want to use "cmake" (see www.cmake.org), type - - cmake . -DCMAKE_INSTALL_PREFIX=/path - make - make install - -As when using the simple configure method described above, "/path" points to -the installation directory where you want to put the libpng "lib", "include", -and "bin" subdirectories. - -V. Directory structure - -You can rename the directories that you downloaded (they -might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.8" -or "zlib128") so that you have directories called "zlib" and "libpng". - -Your directory structure should look like this: - - .. (the parent directory) - libpng (this directory) - INSTALL (this file) - README - *.h, *.c => libpng source files - CMakeLists.txt => "cmake" script - configuration files: - configure.ac, configure, Makefile.am, Makefile.in, - autogen.sh, config.guess, ltmain.sh, missing, libpng.pc.in, - libpng-config.in, aclocal.m4, config.h.in, config.sub, - depcomp, install-sh, mkinstalldirs, test-pngtest.sh - contrib - arm-neon, conftest, examples, gregbook, libtests, pngminim, - pngminus, pngsuite, tools, visupng - projects - cbuilder5, owatcom, visualc71, vstudio, xcode - scripts - makefile.* - *.def (module definition files) - etc. - pngtest.png - etc. - zlib - README, *.h, *.c contrib, etc. - -If the line endings in the files look funny, you may wish to get the other -distribution of libpng. It is available in both tar.gz (UNIX style line -endings) and zip (DOS style line endings) formats. - -VI. Building with project files - -If you are building libpng with MSVC, you can enter the -libpng projects\visualc71 or vstudio directory and follow the instructions -in README.txt. - -Otherwise enter the zlib directory and follow the instructions in zlib/README, -then come back here and run "configure" or choose the appropriate -makefile.sys in the scripts directory. - -VII. Building with makefiles - -Copy the file (or files) that you need from the -scripts directory into this directory, for example - -MSDOS example: - - copy scripts\makefile.msc makefile - copy scripts\pnglibconf.h.prebuilt pnglibconf.h - -UNIX example: - - cp scripts/makefile.std makefile - cp scripts/pnglibconf.h.prebuilt pnglibconf.h - -Read the makefile to see if you need to change any source or -target directories to match your preferences. - -Then read pnglibconf.dfa to see if you want to make any configuration -changes. - -Then just run "make" which will create the libpng library in -this directory and "make test" which will run a quick test that reads -the "pngtest.png" file and writes a "pngout.png" file that should be -identical to it. Look for "9782 zero samples" in the output of the -test. For more confidence, you can run another test by typing -"pngtest pngnow.png" and looking for "289 zero samples" in the output. -Also, you can run "pngtest -m contrib/pngsuite/*.png" and compare -your output with the result shown in contrib/pngsuite/README. - -Most of the makefiles will allow you to run "make install" to -put the library in its final resting place (if you want to -do that, run "make install" in the zlib directory first if necessary). -Some also allow you to run "make test-installed" after you have -run "make install". - -VIII. Configuring libpng for 16-bit platforms - -You will want to look into zconf.h to tell zlib (and thus libpng) that -it cannot allocate more than 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. - -IX. 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. - -X. 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 *". - -XI. Prepending a prefix to exported symbols - -Starting with libpng-1.6.0, you can configure libpng (when using the -"configure" script) to prefix all exported symbols by means of the -configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any -string beginning with a letter and containing only uppercase -and lowercase letters, digits, and the underscore (i.e., a C language -identifier). This creates a set of macros in pnglibconf.h, so this is -transparent to applications; their function calls get transformed by -the macros to use the modified names. - -XII. 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. - -XIII. 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. - -XIV. Enabling or disabling hardware optimizations - -Certain hardware capabilites, such as the Intel SSE instructions, -are normally detected at run time. Enable them with configure options -such as one of - - --enable-arm-neon=yes - --enable-mips-msa=yes - --enable-intel-sse=yes - --enable-powerpc-vsx=yes - -or enable them all at once with - - --enable-hardware-optimizations=yes - -or, if you are not using "configure", you can use one -or more of - - CPPFLAGS += "-DPNG_ARM_NEON" - CPPFLAGS += "-DPNG_MIPS_MSA" - CPPFLAGS += "-DPNG_INTEL_SSE" - CPPFLAGS += "-DPNG_POWERPC_VSX" - -See for example scripts/makefile.linux-opt - -If you wish to avoid using them, -you can disable them via the configure option - - --disable-hardware-optimizations - -to disable them all, or - - --enable-intel-sse=no - -to disable a particular one, -or via compiler-command options such as - - CPPFLAGS += "-DPNG_ARM_NEON_OPT=0, -DPNG_MIPS_MSA_OPT=0, - -DPNG_INTEL_SSE_OPT=0, -DPNG_POWERPC_VSX_OPT=0" - -If you are using cmake, hardware optimizations are "on" -by default. To disable them, use - - cmake . -DPNG_ARM_NEON=no -DPNG_INTEL_SSE=no \ - -DPNG_MIPS_MSA=no -DPNG_POWERPC_VSX=no - -or disable them all at once with - - cmake . -DPNG_HARDWARE_OPTIMIZATIONS=no - -XV. Changes to the build and configuration of libpng in libpng-1.5.x - -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. - -A. Specific changes to library configuration capabilities - -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. - -B. 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, at the time 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 formerly used alternative of adding a list of feature macros to the -CPPFLAGS 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 switched off. 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 also illustrate a case where pngusr.h is still required. - -After you have built libpng, the definitions that were recorded in -pnglibconf.h are available to your application (pnglibconf.h is included -in png.h and gets installed alongside png.h and pngconf.h in your -$PREFIX/include directory). Do not edit pnglibconf.h after you have built -libpng, because than the settings would not accurately reflect the settings -that were used to build libpng. - -XVI. Setjmp/longjmp issues - -Libpng uses setjmp()/longjmp() for error handling. Unfortunately setjmp() -is known to be not thread-safe on some platforms and we don't know of -any platform where it is guaranteed to be thread-safe. Therefore, if -your application is going to be using multiple threads, you should -configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with --DPNG_NO_SETJMP on your compile line, or with - - #undef PNG_SETJMP_SUPPORTED - -in your pnglibconf.h or pngusr.h. - -Starting with libpng-1.6.0, the library included a "simplified API". -This requires setjmp/longjmp, so you must either build the library -with PNG_SETJMP_SUPPORTED defined, or with PNG_SIMPLIFIED_READ_SUPPORTED -and PNG_SIMPLIFIED_WRITE_SUPPORTED undefined. - -XVII. Common linking failures - -If your application fails to find libpng or zlib entries while linking: - - Be sure "-lz" appears after "-lpng" on your linking command. - - Be sure you have built libpng, zlib, and your application for the - same platform (e.g., 32-bit or 64-bit). - - If you are using the vstudio project, observe the WARNING in - project/vstudio/README.txt. - -XVIII. Other sources of information about libpng: - -Further information can be found in the README and libpng-manual.txt -files, in the individual makefiles, in png.h, and the manual pages -libpng.3 and png.5. - -Copyright (c) 1998-2002,2006-2016 Glenn Randers-Pehrson -This document is released under the libpng license. -For conditions of distribution and use, see the disclaimer -and license in png.h. diff --git a/libs/freeimage/src/LibPNG/README b/libs/freeimage/src/LibPNG/README deleted file mode 100644 index 0da5a5ef83..0000000000 --- a/libs/freeimage/src/LibPNG/README +++ /dev/null @@ -1,222 +0,0 @@ -README for libpng version 1.6.34 - September 29, 2017 (shared library 16.0) -See the note about version numbers near the top of png.h - -See INSTALL for instructions on how to install libpng. - -Libpng comes in several distribution formats. Get libpng-*.tar.gz or -libpng-*.tar.xz or if you want UNIX-style line endings in the text files, -or lpng*.7z or lpng*.zip if you want DOS-style line endings. - -Version 0.89 was the first official release of libpng. Don't let the -fact that it's the first release fool you. The libpng library has been in -extensive use and testing since mid-1995. By late 1997 it had -finally gotten to the stage where there hadn't been significant -changes to the API in some time, and people have a bad feeling about -libraries with versions < 1.0. Version 1.0.0 was released in -March 1998. - -**** -Note that some of the changes to the png_info structure render this -version of the library binary incompatible with libpng-0.89 or -earlier versions if you are using a shared library. The type of the -"filler" parameter for png_set_filler() has changed from png_byte to -png_uint_32, which will affect shared-library applications that use -this function. - -To avoid problems with changes to the internals of the png info_struct, -new APIs have been made available in 0.95 to avoid direct application -access to info_ptr. These functions are the png_set_ and -png_get_ functions. These functions should be used when -accessing/storing the info_struct data, rather than manipulating it -directly, to avoid such problems in the future. - -It is important to note that the APIs did not make current programs -that access the info struct directly incompatible with the new -library, through libpng-1.2.x. In libpng-1.4.x, which was meant to -be a transitional release, members of the png_struct and the -info_struct can still be accessed, but the compiler will issue a -warning about deprecated usage. Since libpng-1.5.0, direct access -to these structs is not allowed, and the definitions of the structs -reside in private pngstruct.h and pnginfo.h header files that are not -accessible to applications. It is strongly suggested that new -programs use the new APIs (as shown in example.c and pngtest.c), and -older programs be converted to the new format, to facilitate upgrades -in the future. -**** - -Additions since 0.90 include the ability to compile libpng as a -Windows DLL, and new APIs for accessing data in the info struct. -Experimental functions include the ability to set weighting and cost -factors for row filter selection, direct reads of integers from buffers -on big-endian processors that support misaligned data access, faster -methods of doing alpha composition, and more accurate 16->8 bit color -conversion. - -The additions since 0.89 include the ability to read from a PNG stream -which has had some (or all) of the signature bytes read by the calling -application. This also allows the reading of embedded PNG streams that -do not have the PNG file signature. As well, it is now possible to set -the library action on the detection of chunk CRC errors. It is possible -to set different actions based on whether the CRC error occurred in a -critical or an ancillary chunk. - -The changes made to the library, and bugs fixed are based on discussions -on the PNG-implement mailing list and not on material submitted -privately to Guy, Andreas, or Glenn. They will forward any good -suggestions to the list. - -For a detailed description on using libpng, read libpng-manual.txt. For -examples of libpng in a program, see example.c and pngtest.c. For usage -information and restrictions (what little they are) on libpng, see -png.h. For a description on using zlib (the compression library used by -libpng) and zlib's restrictions, see zlib.h - -I have included a general makefile, as well as several machine and -compiler specific ones, but you may have to modify one for your own needs. - -You should use zlib 1.0.4 or later to run this, but it MAY work with -versions as old as zlib 0.95. Even so, there are bugs in older zlib -versions which can cause the output of invalid compression streams for -some images. You will definitely need zlib 1.0.4 or later if you are -taking advantage of the MS-DOS "far" structure allocation for the small -and medium memory models. You should also note that zlib is a -compression library that is useful for more things than just PNG files. -You can use zlib as a drop-in replacement for fread() and fwrite() if -you are so inclined. - -zlib should be available at the same place that libpng is, or at zlib.net. - -You may also want a copy of the PNG specification. It is available -as an RFC, a W3C Recommendation, and an ISO/IEC Standard. You can find -these at http://www.libpng.org/pub/png/pngdocs.html . - -This code is currently being archived at libpng.sourceforge.io in the -[DOWNLOAD] area, and at http://libpng.download/src . If you -can't find it in any of those places, e-mail me, and I'll help you find it. - -I am not a lawyer, but I believe that the Export Control Classification -Number (ECCN) for libpng is EAR99, which means not subject to export -controls or International Traffic in Arms Regulations (ITAR) because it -is open source, publicly available software, that does not contain any -encryption software. See the EAR, paragraphs 734.3(b)(3) and 734.7(b). - -If you have any code changes, requests, problems, etc., please e-mail -them to me. Also, I'd appreciate any make files or project files, -and any modifications you needed to make to get libpng to compile, -along with a #define variable to tell what compiler/system you are on. -If you needed to add transformations to libpng, or wish libpng would -provide the image in a different way, drop me a note (and code, if -possible), so I can consider supporting the transformation. -Finally, if you get any warning messages when compiling libpng -(note: not zlib), and they are easy to fix, I'd appreciate the -fix. Please mention "libpng" somewhere in the subject line. Thanks. - -This release was created and will be supported by myself (of course -based in a large way on Guy's and Andreas' earlier work), and the PNG -development group. - -Send comments/corrections/commendations to png-mng-implement at -lists.sourceforge.net (subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-implement -to subscribe) or to glennrp at users.sourceforge.net - -You can't reach Guy, the original libpng author, at the addresses -given in previous versions of this document. He and Andreas will -read mail addressed to the png-implement list, however. - -Please do not send general questions about PNG. Send them to -png-mng-misc at lists.sf.net (subscription required; visit -https://lists.sourceforge.net/lists/listinfo/png-mng-misc to -subscribe). If you have a question about something -in the PNG specification that is related to using libpng, send it -to me. Send me any questions that start with "I was using libpng, -and ...". If in doubt, send questions to me. I'll bounce them -to others, if necessary. - -Please do not send suggestions on how to change PNG. We have -been discussing PNG for twenty years now, and it is official and -finished. If you have suggestions for libpng, however, I'll -gladly listen. Even if your suggestion is not used immediately, -it may be used later. - -Files in this distribution: - - ANNOUNCE => Announcement of this version, with recent changes - CHANGES => Description of changes between libpng versions - KNOWNBUG => List of known bugs and deficiencies - LICENSE => License to use and redistribute libpng - README => This file - TODO => Things not implemented in the current library - Y2KINFO => Statement of Y2K compliance - example.c => Example code for using libpng functions - libpng.3 => manual page for libpng (includes libpng-manual.txt) - libpng-manual.txt => Description of libpng and its functions - libpngpf.3 => manual page for libpng's private functions - png.5 => manual page for the PNG format - png.c => Basic interface functions common to library - png.h => Library function and interface declarations (public) - pngpriv.h => Library function and interface declarations (private) - pngconf.h => System specific library configuration (public) - pngstruct.h => png_struct declaration (private) - pnginfo.h => png_info struct declaration (private) - pngdebug.h => debugging macros (private) - pngerror.c => Error/warning message I/O functions - pngget.c => Functions for retrieving info from struct - pngmem.c => Memory handling functions - pngbar.png => PNG logo, 88x31 - pngnow.png => PNG logo, 98x31 - pngpread.c => Progressive reading functions - pngread.c => Read data/helper high-level functions - pngrio.c => Lowest-level data read I/O functions - pngrtran.c => Read data transformation functions - pngrutil.c => Read data utility functions - pngset.c => Functions for storing data into the info_struct - pngtest.c => Library test program - pngtest.png => Library test sample image - pngtrans.c => Common data transformation functions - pngwio.c => Lowest-level write I/O functions - pngwrite.c => High-level write functions - pngwtran.c => Write data transformations - pngwutil.c => Write utility functions - arm => Contains optimized code for the ARM platform - powerpc => Contains optimized code for the PowerPC platform - contrib => Contributions - arm-neon => Optimized code for ARM-NEON platform - powerpc-vsx => Optimized code for POWERPC-VSX platform - examples => Example programs - gregbook => source code for PNG reading and writing, from - Greg Roelofs' "PNG: The Definitive Guide", - O'Reilly, 1999 - libtests => Test programs - mips-msa => Optimized code for MIPS-MSA platform - pngminim => Minimal decoder, encoder, and progressive decoder - programs demonstrating use of pngusr.dfa - pngminus => Simple pnm2png and png2pnm programs - pngsuite => Test images - testpngs - tools => Various tools - visupng => Contains a MSVC workspace for VisualPng - intel => Optimized code for INTEL-SSE2 platform - mips => Optimized code for MIPS platform - projects => Contains project files and workspaces for - building a DLL - owatcom => Contains a WATCOM project for building libpng - visualc71 => Contains a Microsoft Visual C++ (MSVC) - workspace for building libpng and zlib - vstudio => Contains a Microsoft Visual C++ (MSVC) - workspace for building libpng and zlib - scripts => Directory containing scripts for building libpng: - (see scripts/README.txt for the list of scripts) - -Good luck, and happy coding. - --Glenn Randers-Pehrson (current maintainer, since 1998) - Internet: glennrp at users.sourceforge.net - --Andreas Eric Dilger (former maintainer, 1996-1997) - Internet: adilger at enel.ucalgary.ca - Web: http://www-mddsp.enel.ucalgary.ca/People/adilger/ - --Guy Eric Schalnat (original author and former maintainer, 1995-1996) - (formerly of Group 42, Inc) - Internet: gschal at infinet.com diff --git a/libs/freeimage/src/LibPNG/TODO b/libs/freeimage/src/LibPNG/TODO deleted file mode 100644 index 36d6092a2e..0000000000 --- a/libs/freeimage/src/LibPNG/TODO +++ /dev/null @@ -1,30 +0,0 @@ -/* -TODO - list of things to do for libpng: - -Final bug fixes. -Better C++ wrapper/full C++ implementation? -Fix problem with C++ and EXTERN "C". -cHRM transformation. -Remove setjmp/longjmp usage in favor of returning error codes. As a start on - this, minimize the use of png_error(), replacing them with - png_warning(); return(0); or similar. -Palette creation. -Add "grayscale->palette" transformation and "palette->grayscale" detection. -Improved dithering. -Multi-lingual error and warning message support. -Complete sRGB transformation (presently it simply uses gamma=0.45455). -Man pages for function calls. -Better documentation. -Better filter selection - (counting huffman bits/precompression? filter inertia? filter costs?). -Histogram creation. -Text conversion between different code pages (Latin-1 -> Mac and DOS). -Avoid building gamma tables whenever possible. -Use greater precision when changing to linear gamma for compositing against - background and doing rgb-to-gray transformation. -Investigate pre-incremented loop counters and other loop constructions. -Add interpolated method of handling interlacing. -Extend pngvalid.c to validate more of the libpng transformations. -Refactor preprocessor conditionals to compile entire statements - -*/ diff --git a/libs/freeimage/src/LibPNG/libpng-manual.txt b/libs/freeimage/src/LibPNG/libpng-manual.txt deleted file mode 100644 index d4407ef2ea..0000000000 --- a/libs/freeimage/src/LibPNG/libpng-manual.txt +++ /dev/null @@ -1,5464 +0,0 @@ -libpng-manual.txt - A description on how to use and modify libpng - - libpng version 1.6.34 - September 29, 2017 - Updated and distributed by Glenn Randers-Pehrson - - Copyright (c) 1998-2017 Glenn Randers-Pehrson - - This document is released under the libpng license. - For conditions of distribution and use, see the disclaimer - and license in png.h - - Based on: - - libpng versions 0.97, January 1998, through 1.6.34 - September 29, 2017 - Updated and distributed by Glenn Randers-Pehrson - Copyright (c) 1998-2017 Glenn Randers-Pehrson - - libpng 1.0 beta 6 - version 0.96 - May 28, 1997 - Updated and distributed by Andreas Dilger - Copyright (c) 1996, 1997 Andreas Dilger - - libpng 1.0 beta 2 - version 0.88 - January 26, 1996 - For conditions of distribution and use, see copyright - notice in png.h. Copyright (c) 1995, 1996 Guy Eric - Schalnat, Group 42, Inc. - - Updated/rewritten per request in the libpng FAQ - Copyright (c) 1995, 1996 Frank J. T. Wojcik - December 18, 1995 & January 20, 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. 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 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 -the libpng distribution. - -Libpng was written as a companion to the PNG specification, as a way -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:2004 (E)) at -. -It is technically equivalent -to the PNG specification (second edition) but has some additional material. - -The PNG-1.0 specification is available 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, 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 -complete as possible, while keeping the code easy to understand. -Currently, this library only supports C. Support for other languages -is being considered. - -Libpng has been designed to handle multiple sessions at one time, -to be easily modifiable, to be portable to the vast majority of -machines (ANSI, K&R, 16-, 32-, and 64-bit) available, and to be easy -to use. The ultimate goal of libpng is to promote the acceptance of -the PNG file format in whatever way possible. While there is still -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. -You can usually find the source files for the zlib utility wherever you -find the libpng source files. - -Libpng is thread safe, provided the threads are using different -instances of the structures. Each thread should have its own -png_struct and png_info instances, and thus its own image. -Libpng does not protect itself against two threads using the -same instance of a structure. - -II. Structures - -There are two main structures that are important to libpng, png_struct -and png_info. Both are internal structures that are no longer exposed -in the libpng interface (as of libpng 1.5.0). - -The png_info structure is designed to provide information about the -PNG file. At one time, the fields of png_info were intended to be -directly accessible to the user. However, this tended to cause problems -with applications using dynamically loaded libraries, and as a result -a set of interface functions for png_info (the png_get_*() and png_set_*() -functions) was developed, and direct access to the png_info fields was -deprecated.. - -The png_struct structure is the object used by the library to decode a -single image. As of 1.5.0 this structure is also not exposed. - -Almost all libpng APIs require a pointer to a png_struct as the first argument. -Many (in particular the png_set and png_get APIs) also require a pointer -to png_info as the second argument. Some application visible macros -defined in png.h designed for basic data access (reading and writing -integers in the PNG format) don't take a png_info pointer, but it's almost -always safe to assume that a (png_struct*) has to be passed to call an API -function. - -You can have more than one png_info structure associated with an image, -as illustrated in pngtest.c, one for information valid prior to the -IDAT chunks and another (called "end_info" below) for things after them. - -The png.h header file is an invaluable reference for programming with libpng. -And while I'm on the topic, make sure you include the libpng header file: - -#include - -and also (as of libpng-1.5.0) the zlib header file, if you need it: - -#include - -Types - -The png.h header file defines a number of integral types used by the -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 -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). - -All APIs that take (double) arguments also have a matching API that -takes the corresponding fixed point integer arguments. The fixed point -API has the same name as the floating point one with "_fixed" appended. -The actual range of values permitted in the APIs is frequently less than -the full range of (png_fixed_point) (-21474 to +21474). When APIs require -a non-negative argument the type is recorded as png_uint_32 above. Consult -the header file and the text below for more information. - -Special care must be take with sCAL chunk handling because the chunk itself -uses non-integral values encoded as strings containing decimal floating point -numbers. See the comments in the header file. - -Configuration - -The main header file function declarations are frequently protected by C -preprocessing directives of the form: - - #ifdef PNG_feature_SUPPORTED - declare-function - #endif - ... - #ifdef PNG_feature_SUPPORTED - use-function - #endif - -The library can be built without support for these APIs, although a -standard build will have all implemented APIs. Application programs -should check the feature macros before using an API for maximum -portability. From libpng 1.5.0 the feature macros set during the build -of libpng are recorded in the header file "pnglibconf.h" and this file -is always included by png.h. - -If you don't need to change the library configuration from the default, skip to -the next section ("Reading"). - -Notice that some of the makefiles in the 'scripts' directory and (in 1.5.0) all -of the build project files in the 'projects' directory simply copy -scripts/pnglibconf.h.prebuilt to pnglibconf.h. This means that these build -systems do not permit easy auto-configuration of the library - they only -support the default configuration. - -The easiest way to make minor changes to the libpng configuration when -auto-configuration is supported is to add definitions to the command line -using (typically) CPPFLAGS. For example: - -CPPFLAGS=-DPNG_NO_FLOATING_ARITHMETIC - -will change the internal libpng math implementation for gamma correction and -other arithmetic calculations to fixed point, avoiding the need for fast -floating point support. The result can be seen in the generated pnglibconf.h - -make sure it contains the changed feature macro setting. - -If you need to make more extensive configuration changes - more than one or two -feature macro settings - you can either add -DPNG_USER_CONFIG to the build -command line and put a list of feature macro settings in pngusr.h or you can set -DFA_XTRA (a makefile variable) to a file containing the same information in the -form of 'option' settings. - -A. Changing pnglibconf.h - -A variety of methods exist to build libpng. Not all of these support -reconfiguration of pnglibconf.h. To reconfigure pnglibconf.h it must either be -rebuilt from scripts/pnglibconf.dfa using awk or it must be edited by hand. - -Hand editing is achieved by copying scripts/pnglibconf.h.prebuilt to -pnglibconf.h and changing the lines defining the supported features, paying -very close attention to the 'option' information in scripts/pnglibconf.dfa -that describes those features and their requirements. This is easy to get -wrong. - -B. Configuration using DFA_XTRA - -Rebuilding from pnglibconf.dfa is easy if a functioning 'awk', or a later -variant such as 'nawk' or 'gawk', is available. The configure build will -automatically find an appropriate awk and build pnglibconf.h. -The scripts/pnglibconf.mak file contains a set of make rules for doing the -same thing if configure is not used, and many of the makefiles in the scripts -directory use this approach. - -When rebuilding simply write a new file containing changed options and set -DFA_XTRA to the name of this file. This causes the build to append the new file -to the end of scripts/pnglibconf.dfa. The pngusr.dfa file should contain lines -of the following forms: - -everything = off - -This turns all optional features off. Include it at the start of pngusr.dfa to -make it easier to build a minimal configuration. You will need to turn at least -some features on afterward to enable either reading or writing code, or both. - -option feature on -option feature off - -Enable or disable a single feature. This will automatically enable other -features required by a feature that is turned on or disable other features that -require a feature which is turned off. Conflicting settings will cause an error -message to be emitted by awk. - -setting feature default value - -Changes the default value of setting 'feature' to 'value'. There are a small -number of settings listed at the top of pnglibconf.h, they are documented in the -source code. Most of these values have performance implications for the library -but most of them have no visible effect on the API. Some can also be overridden -from the API. - -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_USER_CONFIG - -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. - -Apart from the global setting "everything = off" all the options listed above -can be set using macros in pngusr.h: - -#define PNG_feature_SUPPORTED - -is equivalent to: - -option feature on - -#define PNG_NO_feature - -is equivalent to: - -option feature off - -#define PNG_feature value - -is equivalent to: - -setting feature default value - -Notice that in both cases, pngusr.dfa and pngusr.h, the contents of the -pngusr file you supply override the contents of scripts/pnglibconf.dfa - -If confusing or incomprehensible behavior results it is possible to -examine the intermediate file pnglibconf.dfn to find the full set of -dependency information for each setting and option. Simply locate the -feature in the file and read the C comments that precede it. - -This method is also illustrated in the contrib/pngminim/* makefiles and -pngusr.h. - -III. Reading - -We'll now walk you through the possible functions to call when reading -in a PNG file sequentially, briefly explaining the syntax and purpose -of each one. See example.c and png.h for more detail. While -progressive reading is covered in the next section, you will still -need some of the functions discussed in this section to read a PNG -file. - -Setup - -You will want to do the I/O initialization(*) before you get into libpng, -so if it doesn't work, you don't have much to undo. Of course, you -will also want to insure that you are, in fact, dealing with a PNG -file. Libpng provides a simple check to see if a file is a PNG file. -To use it, pass in the first 1 to 8 bytes of the file to the function -png_sig_cmp(), and it will return 0 (false) if the bytes match the -corresponding bytes of the PNG signature, or nonzero (true) otherwise. -Of course, the more bytes you pass in, the greater the accuracy of the -prediction. - -If you are intending to keep the file pointer open for use in libpng, -you must ensure you don't read more than 8 bytes from the beginning -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. - -(*): If you are not using the standard I/O functions, you will need -to replace them with custom functions. See the discussion under -Customizing libpng. - - FILE *fp = fopen(file_name, "rb"); - if (!fp) - { - return (ERROR); - } - - 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 -allocate the structures. We also pass the library version, optional -pointers to error handling functions, and a pointer to a data struct for -use by the error functions, if necessary (the pointer and functions can -be NULL if the default error handlers are to be used). See the section -on Changes to Libpng below regarding the old initialization functions. -The structure allocation functions quietly return NULL if they fail to -create the structure, so your application should check for that. - - png_structp png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - - if (!png_ptr) - return (ERROR); - - png_infop info_ptr = png_create_info_struct(png_ptr); - - if (!info_ptr) - { - png_destroy_read_struct(&png_ptr, - (png_infopp)NULL, (png_infopp)NULL); - return (ERROR); - } - -If you want to use your own memory allocation routines, -use a libpng that was built with PNG_USER_MEM_SUPPORTED defined, 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. - -When libpng encounters an error, it expects to longjmp back -to your routine. Therefore, you will need to call setjmp and pass -your png_jmpbuf(png_ptr). If you read the file from different -routines, you will need to update the longjmp buffer 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 an error occurs, and libpng longjmp's -back to your setjmp, you will want to call png_destroy_read_struct() to -free any memory. - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - &end_info); - fclose(fp); - return (ERROR); - } - -Pass (png_infopp)NULL instead of &end_info if you didn't create -an end_info structure. - -If you would rather avoid the complexity of setjmp/longjmp issues, -you can compile libpng with PNG_NO_SETJMP, in which case -errors will result in a call to PNG_ABORT() which defaults to abort(). - -You can #define PNG_ABORT() to a function that does something -more useful than abort(), as long as your function does not -return. - -Now you need to set up the input code. The default for libpng is to -use the C function fread(). If you use this, you will need to pass a -valid FILE * in the function png_init_io(). Be sure that the file is -opened in binary mode. If you wish to handle reading data in another -way, you need not call the png_init_io() function, but you must then -implement the libpng I/O methods discussed in the Customizing Libpng -section below. - - png_init_io(png_ptr, fp); - -If you had previously opened the file and read any of the signature from -the beginning in order to see if this was a PNG file, you need to let -libpng know that there are some bytes missing from the start of the file. - - png_set_sig_bytes(png_ptr, number); - -You can change the zlib compression buffer size to be used while -reading compressed data with - - png_set_compression_buffer_size(png_ptr, buffer_size); - -where the default size is 8192 bytes. Note that the buffer size -is changed immediately and the buffer is reallocated immediately, -instead of setting a flag to be acted upon later. - -If you want CRC errors to be handled in a different manner than -the default, use - - png_set_crc_action(png_ptr, crit_action, ancil_action); - -The values for png_set_crc_action() say how libpng is to handle CRC errors in -ancillary and critical chunks, and whether to use the data contained -therein. Starting with libpng-1.6.26, this also governs how an ADLER32 error -is handled while reading the IDAT chunk. Note that it is impossible to -"discard" data in a critical chunk. - -Choices for (int) crit_action are - PNG_CRC_DEFAULT 0 error/quit - PNG_CRC_ERROR_QUIT 1 error/quit - PNG_CRC_WARN_USE 3 warn/use data - PNG_CRC_QUIET_USE 4 quiet/use data - PNG_CRC_NO_CHANGE 5 use the current value - -Choices for (int) ancil_action are - PNG_CRC_DEFAULT 0 error/quit - PNG_CRC_ERROR_QUIT 1 error/quit - PNG_CRC_WARN_DISCARD 2 warn/discard data - PNG_CRC_WARN_USE 3 warn/use data - PNG_CRC_QUIET_USE 4 quiet/use data - PNG_CRC_NO_CHANGE 5 use the current value - -When the setting for crit_action is PNG_CRC_QUIET_USE, the CRC and ADLER32 -checksums are not only ignored, but they are not evaluated. - -Setting up callback code - -You can set up a callback function to handle any unknown chunks in the -input stream. You must supply the function - - read_chunk_callback(png_structp png_ptr, - png_unknown_chunkp chunk); - { - /* The unknown chunk structure contains your - chunk data, along with similar data for any other - unknown chunks: */ - - png_byte name[5]; - png_byte *data; - png_size_t size; - - /* Note that libpng has already taken care of - the CRC handling */ - - /* put your code here. Search for your chunk in the - unknown chunk structure, process it, and return one - of the following: */ - - return (-n); /* chunk had an error */ - return (0); /* did not recognize */ - return (n); /* success */ - } - -(You can give your function another name that you like instead of -"read_chunk_callback") - -To inform libpng about your function, use - - png_set_read_user_chunk_fn(png_ptr, user_chunk_ptr, - read_chunk_callback); - -This names not only the callback function, but also a user pointer that -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 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 -a progress meter or the like. It's demonstrated in pngtest.c. -You must supply a function - - void read_row_callback(png_structp png_ptr, - png_uint_32 row, int pass); - { - /* put your code here */ - } - -(You can give it another name that you like instead of "read_row_callback") - -To inform libpng about your function, use - - png_set_read_status_fn(png_ptr, read_row_callback); - -When this function is called the row has already been completely processed and -the 'row' and 'pass' refer to the next row to be handled. For the -non-interlaced case the row that was just handled is simply one less than the -passed in row number, and pass will always be 0. For the interlaced case the -same applies unless the row value is 0, in which case the row just handled was -the last one from one of the preceding passes. Because interlacing may skip a -pass you cannot be sure that the preceding pass is just 'pass-1'; if you really -need to know what the last pass is record (row,pass) from the callback and use -the last recorded value each time. - -As with the user transform you can find the output row using the -PNG_ROW_FROM_PASS_ROW macro. - -Unknown-chunk handling - -Now you get to set the way the library processes unknown chunks in the -input PNG stream. Both known and unknown chunks will be read. Normal -behavior is that known chunks will be parsed into information in -various info_ptr members while unknown chunks will be discarded. This -behavior can be wasteful if your application will never use some known -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 - 3: keep even if unsafe-to-copy - - You can use these definitions: - PNG_HANDLE_CHUNK_AS_DEFAULT 0 - PNG_HANDLE_CHUNK_NEVER 1 - PNG_HANDLE_CHUNK_IF_SAFE 2 - PNG_HANDLE_CHUNK_ALWAYS 3 - - chunk_list - list of chunks affected (a byte string, - five bytes per chunk, NULL or '\0' if - num_chunks is positive; ignored if - numchunks <= 0). - - num_chunks - number of chunks affected; if 0, all - 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 -known to libpng is named in the list, it will be handled as unknown, -according to the "keep" directive. If a chunk is named in successive -instances of png_set_keep_unknown_chunks(), the final instance will -take precedence. The IHDR and IEND chunks should not be named in -chunk_list; if they are, libpng will process them normally anyway. -If you know that your application will never make use of some particular -chunks, use PNG_HANDLE_CHUNK_NEVER (or 1) as demonstrated below. - -Here is an example of the usage of png_set_keep_unknown_chunks(), -where the private "vpAg" chunk will later be processed by a user chunk -callback function: - - png_byte vpAg[5]={118, 112, 65, 103, (png_byte) '\0'}; - - #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) - png_byte unused_chunks[]= - { - 104, 73, 83, 84, (png_byte) '\0', /* hIST */ - 105, 84, 88, 116, (png_byte) '\0', /* iTXt */ - 112, 67, 65, 76, (png_byte) '\0', /* pCAL */ - 115, 67, 65, 76, (png_byte) '\0', /* sCAL */ - 115, 80, 76, 84, (png_byte) '\0', /* sPLT */ - 116, 73, 77, 69, (png_byte) '\0', /* tIME */ - }; - #endif - - ... - - #if defined(PNG_UNKNOWN_CHUNKS_SUPPORTED) - /* 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); - #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. -For safety, libpng imposes a default limit of 1 million rows and columns. -Larger images will be rejected immediately with a png_error() call. If -you wish to change these limits, you can use - - png_set_user_limits(png_ptr, width_max, height_max); - -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 -before calling png_read_info(), png_read_png(), or png_process_data(). - -When writing a PNG datastream, put this statement before calling -png_write_info() or png_write_png(). - -If you need to retrieve the limits that are being applied, use - - width_max = png_get_user_width_max(png_ptr); - height_max = png_get_user_height_max(png_ptr); - -The PNG specification sets no limit on the number of ancillary chunks -allowed in a PNG datastream. By default, libpng imposes a limit of -a total of 1000 sPLT, tEXt, iTXt, zTXt, and unknown chunks to be stored. -If you have set up both info_ptr and end_info_ptr, the limit applies -separately to each. You can change the limit on the total number of such -chunks that will be stored, with - - png_set_chunk_cache_max(png_ptr, user_chunk_cache_max); - -where 0x7fffffffL means unlimited. You can retrieve this limit with - - chunk_cache_max = png_get_chunk_cache_max(png_ptr); - -Libpng imposes a limit of 8 Megabytes (8,000,000 bytes) on the amount of -memory that any chunk other than IDAT can occupy, originally or when -decompressed (prior to libpng-1.6.32 the limit was only applied to compressed -chunks after decompression). You can change this limit with - - png_set_chunk_malloc_max(png_ptr, user_chunk_malloc_max); - -and you can retrieve the limit with - - chunk_malloc_max = png_get_chunk_malloc_max(png_ptr); - -Any chunks that would cause either of these limits to be exceeded will -be ignored. - -Information about your system - -If you intend to display the PNG or to incorporate it in other image data you -need to tell libpng information about your display or drawing surface so that -libpng can convert the values in the image to match the display. - -From libpng-1.5.4 this information can be set before reading the PNG file -header. In earlier versions png_set_gamma() existed but behaved incorrectly if -called before the PNG file header had been read and png_set_alpha_mode() did not -exist. - -If you need to support versions prior to libpng-1.5.4 test the version number -as illustrated below using "PNG_LIBPNG_VER >= 10504" and follow the procedures -described in the appropriate manual page. - -You give libpng the encoding expected by your system expressed as a 'gamma' -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, output_gamma); - -or you can use the fixed point equivalent: - - 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 -too contrasty or washed out you got the value wrong - check your system -documentation! - -Many systems permit the system gamma to be changed via a lookup table in the -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. - -You would use the linear (unencoded) value if you need to process the pixel -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 -suitable background, as described in the PNG specification. - -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 - -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 -file gamma default to 1/screen_gamma, so normally you don't need to call -png_set_gamma. If you need different defaults call png_set_gamma() before -png_set_alpha_mode() - if you call it after it will override the settings made -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. - -You should normally use this format if you intend to perform -color correction on the color values; most, maybe all, color -correction software has no handling for the alpha channel and, -anyway, the math to handle pre-multiplied component values is -unnecessarily complex. - -Before you do any arithmetic on the component values you need -to remove the gamma encoding and multiply out the alpha -channel. See the PNG specification for more detail. It is -important to note that when an image with an alpha channel is -scaled, linear encoded, pre-multiplied component values must -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!). 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. - -With this format the final image must be re-encoded to -match the display gamma before the image is displayed. -If your system doesn't do that, yet still seems to -perform arithmetic on the pixels without decoding them, -it is broken - check out the modes below. - -With PNG_ALPHA_STANDARD libpng always produces linear -component values, whatever screen_gamma you supply. The -screen_gamma value is, however, used as a default for -the file gamma if the PNG file has no gamma information. - -If you call png_set_gamma() after png_set_alpha_mode() you -will override the linear encoding. Instead the -pre-multiplied pixel values will be gamma encoded but -the alpha channel will still be linear. This may -actually match the requirements of some broken software, -but it is unlikely. - -While linear 8-bit data is often used it has -insufficient precision for any image with a reasonable -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 -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 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 -non-opaque pixels. - -In normal compositing, where the alpha channel encodes -partial pixel coverage (as opposed to broad area -translucency), the inaccuracies of the 8-bit -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 -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(): - - png_set_alpha_mode(png_ptr, PNG_ALPHA_PNG, - screen_gamma); - -You can do color correction on the result (libpng does not currently -support color correction internally). When you handle the alpha channel -you need to undo the gamma encoding and multiply out the alpha. - - png_set_alpha_mode(png_ptr, PNG_ALPHA_STANDARD, - screen_gamma); - png_set_expand_16(png_ptr); - -If you are using the high level interface, don't call png_set_expand_16(); -instead pass PNG_TRANSFORM_EXPAND_16 to the interface. - -With this mode you can't do color correction, but you can do arithmetic, -including composition and scaling, on the data without further processing. - - png_set_alpha_mode(png_ptr, PNG_ALPHA_OPTIMIZED, - screen_gamma); - -You can avoid the expansion to 16-bit components with this mode, but you -lose the ability to scale the image or perform other linear arithmetic. -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); - -Choices for the alpha_mode are - - PNG_ALPHA_PNG 0 /* according to the PNG standard */ - PNG_ALPHA_STANDARD 1 /* according to Porter/Duff */ - PNG_ALPHA_ASSOCIATED 1 /* as above; this is the normal practice */ - PNG_ALPHA_PREMULTIPLIED 1 /* as above */ - PNG_ALPHA_OPTIMIZED 2 /* 'PNG' for opaque pixels, else 'STANDARD' */ - PNG_ALPHA_BROKEN 3 /* the alpha channel is gamma encoded */ - -PNG_ALPHA_PNG 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 were 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 -transparent parts of this image. - - png_set_background(png_ptr, &background_color, - PNG_BACKGROUND_GAMMA_SCREEN, 0, 1); - -The background_color is an RGB or grayscale value according to the data format -libpng will produce for you. Because you don't yet know the format of the PNG -file, if you call png_set_background at this point you must arrange for the -format produced by libpng to always have 8-bit or 16-bit components and then -store the color as an 8-bit or 16-bit color as appropriate. The color contains -separate gray and RGB component values, so you can let libpng produce gray or -RGB output according to the input format, but low bit depth grayscale images -must always be converted to at least 8-bit format. (Even though low bit depth -grayscale images can't have an alpha channel they can have a transparent -color!) - -You set the transforms you need later, either as flags to the high level -interface or libpng API calls for the low level interface. For reference the -settings and API calls required are: - -8-bit values: - PNG_TRANSFORM_SCALE_16 | PNG_EXPAND - png_set_expand(png_ptr); png_set_scale_16(png_ptr); - - If you must get exactly the same inaccurate results - produced by default in versions prior to libpng-1.5.4, - use PNG_TRANSFORM_STRIP_16 and png_set_strip_16(png_ptr) - instead. - -16-bit values: - PNG_TRANSFORM_EXPAND_16 - png_set_expand_16(png_ptr); - -In either case palette image data will be expanded to RGB. If you just want -color data you can add PNG_TRANSFORM_GRAY_TO_RGB or png_set_gray_to_rgb(png_ptr) -to the list. - -Calling png_set_background before the PNG file header is read will not work -prior to libpng-1.5.4. Because the failure may result in unexpected warnings or -errors it is therefore much safer to call png_set_background after the head has -been read. Unfortunately this means that prior to libpng-1.5.4 it cannot be -used with the high level interface. - -The high-level read interface - -At this point there are two ways to proceed; through the high-level -read interface, or through a sequence of low-level read operations. -You can use the high-level interface if (a) you are willing to read -the entire image into memory, and (b) the input transformations -you want to do are limited to the following set: - - PNG_TRANSFORM_IDENTITY No transformation - PNG_TRANSFORM_SCALE_16 Strip 16-bit samples to - 8-bit accurately - PNG_TRANSFORM_STRIP_16 Chop 16-bit samples to - 8-bit less accurately - PNG_TRANSFORM_STRIP_ALPHA Discard the alpha channel - PNG_TRANSFORM_PACKING Expand 1, 2 and 4-bit - samples to bytes - PNG_TRANSFORM_PACKSWAP Change order of packed - pixels to LSB first - PNG_TRANSFORM_EXPAND Perform set_expand() - PNG_TRANSFORM_INVERT_MONO Invert monochrome images - PNG_TRANSFORM_SHIFT Normalize pixels to the - sBIT depth - PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA - to BGRA - PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA - to AG - PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity - to transparency - PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples - PNG_TRANSFORM_GRAY_TO_RGB Expand grayscale samples - to RGB (or GA to RGBA) - PNG_TRANSFORM_EXPAND_16 Expand samples to 16 bits - -(This excludes setting a background color, doing gamma transformation, -quantizing, and setting filler.) If this is the case, simply do this: - - png_read_png(png_ptr, info_ptr, png_transforms, NULL) - -where png_transforms is an integer containing the bitwise OR of some -set of transformation flags. This call is equivalent to png_read_info(), -followed the set of transformations indicated by the transform mask, -then png_read_image(), and finally png_read_end(). - -(The final parameter of this call is not yet used. Someday it might point -to transformation parameters required by some future input transform.) - -You must use png_transforms and not call any png_set_transform() functions -when you use png_read_png(). - -After you have called png_read_png(), you can retrieve the image data -with - - row_pointers = png_get_rows(png_ptr, info_ptr); - -where row_pointers is an array of pointers to the pixel data for each row: - - png_bytep row_pointers[height]; - -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/(sizeof (png_byte))) - png_error (png_ptr, - "Image is too tall to process in memory"); - - if (width > PNG_UINT_32_MAX/pixel_size) - png_error (png_ptr, - "Image is too wide to process in memory"); - - row_pointers = png_malloc(png_ptr, - height*(sizeof (png_bytep))); - - for (int i=0; i PNG_SIZE_MAX/(width*pixel_size)) { - png_error(png_ptr,"image_data buffer would be too large"); - } - - png_bytep buffer=png_malloc(png_ptr,height*width*pixel_size); - - for (int i=0; i) and -png_get_(png_ptr, info_ptr, ...) functions return non-zero if the -data has been read, or zero if it is missing. The parameters to the -png_get_ 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); - - palette - the palette for the file - (array of png_color) - - num_palette - number of entries in the palette - - png_get_gAMA(png_ptr, info_ptr, &file_gamma); - png_get_gAMA_fixed(png_ptr, info_ptr, &int_file_gamma); - - file_gamma - the gamma at which the file is - written (PNG_INFO_gAMA) - - 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_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) - - {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) - - {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) - - png_get_sRGB(png_ptr, info_ptr, &srgb_intent); - - 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 - implies specific values of gAMA and - cHRM. - - png_get_iCCP(png_ptr, info_ptr, &name, - &compression_type, &profile, &proflen); - - name - The profile name. - - compression_type - The compression type; always - PNG_COMPRESSION_TYPE_BASE for PNG 1.0. - You may give NULL to this argument to - ignore it. - - profile - International Color Consortium color - profile data. May contain NULs. - - proflen - length of profile data in bytes. - - png_get_sBIT(png_ptr, info_ptr, &sig_bit); - - sig_bit - the number of significant bits for - (PNG_INFO_sBIT) each of the gray, - red, green, and blue channels, - whichever are appropriate for the - given color type (png_color_16) - - png_get_tRNS(png_ptr, info_ptr, &trans_alpha, - &num_trans, &trans_color); - - trans_alpha - array of alpha (transparency) - entries for palette (PNG_INFO_tRNS) - - num_trans - number of transparent entries - (PNG_INFO_tRNS) - - trans_color - graylevel or color sample values of - the single transparent color for - non-paletted images (PNG_INFO_tRNS) - - png_get_eXIf_1(png_ptr, info_ptr, &num_exif, &exif); - (PNG_INFO_eXIf) - - exif - Exif profile (array of png_byte) - - png_get_hIST(png_ptr, info_ptr, &hist); - (PNG_INFO_hIST) - - hist - histogram of palette (array of - png_uint_16) - - png_get_tIME(png_ptr, info_ptr, &mod_time); - - mod_time - time image was last modified - (PNG_VALID_tIME) - - png_get_bKGD(png_ptr, info_ptr, &background); - - background - background color (of type - png_color_16p) (PNG_VALID_bKGD) - valid 16-bit red, green and blue - values, regardless of color_type - - num_comments = png_get_text(png_ptr, info_ptr, - &text_ptr, &num_text); - - num_comments - number of comments - - text_ptr - array of png_text holding image - comments - - text_ptr[i].compression - type of compression used - on "text" PNG_TEXT_COMPRESSION_NONE - PNG_TEXT_COMPRESSION_zTXt - PNG_ITXT_COMPRESSION_NONE - PNG_ITXT_COMPRESSION_zTXt - - text_ptr[i].key - keyword for comment. Must contain - 1-79 characters. - - text_ptr[i].text - text comments for current - keyword. Can be empty. - - text_ptr[i].text_length - length of text string, - after decompression, 0 for iTXt - - text_ptr[i].itxt_length - length of itxt string, - after decompression, 0 for tEXt/zTXt - - text_ptr[i].lang - language of comment (empty - string for unknown). - - text_ptr[i].lang_key - keyword in UTF-8 - (empty string for unknown). - - Note that the itxt_length, lang, and lang_key - members of the text_ptr structure only exist when the - library is built with iTXt chunk support. Prior to - libpng-1.4.0 the library was built by default without - iTXt support. Also note that when iTXt is supported, - they contain NULL pointers when the "compression" - field contains PNG_TEXT_COMPRESSION_NONE or - PNG_TEXT_COMPRESSION_zTXt. - - num_text - number of comments (same as - num_comments; you can put NULL here - to avoid the duplication) - - Note while png_set_text() will accept text, language, - and translated keywords that can be NULL pointers, the - structure returned by png_get_text will always contain - regular zero-terminated C strings. They might be - empty strings but they will never be NULL pointers. - - num_spalettes = png_get_sPLT(png_ptr, info_ptr, - &palette_ptr); - - num_spalettes - number of sPLT chunks read. - - palette_ptr - array of palette structures holding - contents of one or more sPLT chunks - read. - - png_get_oFFs(png_ptr, info_ptr, &offset_x, &offset_y, - &unit_type); - - offset_x - positive offset from the left edge - of the screen (can be negative) - - offset_y - positive offset from the top edge - of the screen (can be negative) - - unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER - - png_get_pHYs(png_ptr, info_ptr, &res_x, &res_y, - &unit_type); - - res_x - pixels/unit physical resolution in - x direction - - res_y - pixels/unit physical resolution in - x direction - - unit_type - PNG_RESOLUTION_UNKNOWN, - PNG_RESOLUTION_METER - - png_get_sCAL(png_ptr, info_ptr, &unit, &width, - &height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - - height - height of a pixel in physical scale units - (width and height are doubles) - - png_get_sCAL_s(png_ptr, info_ptr, &unit, &width, - &height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - (expressed as a string) - - height - height of a pixel in physical scale units - (width and height are strings like "2.54") - - num_unknown_chunks = png_get_unknown_chunks(png_ptr, - info_ptr, &unknowns) - - unknowns - array of png_unknown_chunk - structures holding unknown chunks - - unknowns[i].name - name of unknown chunk - - unknowns[i].data - data of unknown chunk - - unknowns[i].size - size of unknown chunk's data - - unknowns[i].location - position of chunk in file - - The value of "i" corresponds to the order in which the - chunks were read from the PNG file or inserted with the - png_set_unknown_chunks() function. - - The value of "location" is a bitwise "or" of - - PNG_HAVE_IHDR (0x01) - PNG_HAVE_PLTE (0x02) - PNG_AFTER_IDAT (0x08) - -The data from the pHYs chunk can be retrieved in several convenient -forms: - - res_x = png_get_x_pixels_per_meter(png_ptr, - info_ptr) - - res_y = png_get_y_pixels_per_meter(png_ptr, - info_ptr) - - res_x_and_y = png_get_pixels_per_meter(png_ptr, - info_ptr) - - res_x = png_get_x_pixels_per_inch(png_ptr, - info_ptr) - - res_y = png_get_y_pixels_per_inch(png_ptr, - info_ptr) - - res_x_and_y = png_get_pixels_per_inch(png_ptr, - info_ptr) - - aspect_ratio = png_get_pixel_aspect_ratio(png_ptr, - info_ptr) - - Each of these returns 0 [signifying "unknown"] if - the data is not present or if res_x is 0; - res_x_and_y is 0 if res_x != res_y - - Note that because of the way the resolutions are - stored internally, the inch conversions won't - come out to exactly even number. For example, - 72 dpi is stored as 0.28346 pixels/meter, and - when this is retrieved it is 71.9988 dpi, so - be sure to round the returned value appropriately - if you want to display a reasonable-looking result. - -The data from the oFFs chunk can be retrieved in several convenient -forms: - - x_offset = png_get_x_offset_microns(png_ptr, info_ptr); - - y_offset = png_get_y_offset_microns(png_ptr, info_ptr); - - x_offset = png_get_x_offset_inches(png_ptr, info_ptr); - - y_offset = png_get_y_offset_inches(png_ptr, info_ptr); - - Each of these returns 0 [signifying "unknown" if both - x and y are 0] if the data is not present or if the - chunk is present but the unit is the pixel. The - remark about inexact inch conversions applies here - as well, because a value in inches can't always be - converted to microns and back without some loss - of precision. - -For more information, see the -PNG specification for chunk contents. Be careful with trusting -rowbytes, as some of the transformations could increase the space -needed to hold a row (expand, filler, gray_to_rgb, etc.). -See png_read_update_info(), below. - -A quick word about text_ptr and num_text. PNG stores comments in -keyword/text pairs, one pair per chunk, with no limit on the number -of text chunks, and a 2^31 byte limit on their size. While there are -suggested keywords, there is no requirement to restrict the use to these -strings. It is strongly suggested that keywords and text be sensible -to humans (that's the point), so don't use abbreviations. Non-printing -symbols are not allowed. See the PNG specification for more details. -There is also no requirement to have text after the keyword. - -Keywords should be limited to 79 Latin-1 characters without leading or -trailing spaces, but non-consecutive spaces are allowed within the -keyword. It is possible to have the same keyword any number of times. -The text_ptr is an array of png_text structures, each holding a -pointer to a language string, a pointer to a keyword and a pointer to -a text string. The text string, language code, and translated -keyword may be empty or NULL pointers. The keyword/text -pairs are put into the array in the order that they are received. -However, some or all of the text chunks may be after the image, so, to -make sure you have read all the text chunks, don't mess with these -until after you read the stuff after the image. This will be -mentioned again below in the discussion that goes with png_read_end(). - -Input transformations - -After you've read the header information, you can set up the library -to handle any special transformations of the image data. The various -ways to transform the data will be described in the order that they -should occur. This is important, as some of these change the color -type and/or bit depth of the data, and some others only work on -certain color types and bit depths. - -Transformations you request are ignored if they don't have any meaning for a -particular input data format. However some transformations can have an effect -as a result of a previous transformation. If you specify a contradictory set of -transformations, for example both adding and removing the alpha channel, you -cannot predict the final result. - -The color used for the transparency values should be supplied in the same -format/depth as the current image data. It is stored in the same format/depth -as the image data in a tRNS chunk, so this is what libpng expects for this data. - -The color used for the background value depends on the need_expand argument as -described below. - -Data will be decoded into the supplied row buffers packed into bytes -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 RGB RGB RGB format unless png_set_filler() or png_set_add_alpha() -is called to insert filler bytes, either before or after each RGB triplet. - -16-bit RGB data will be returned RRGGBB RRGGBB, with the most significant -byte of the color value first, unless png_set_scale_16() is called to -transform it to regular RGB RGB triplets, or png_set_filler() or -png_set_add alpha() is called to insert two filler bytes, either before -or after each RRGGBB triplet. Similarly, 8-bit or 16-bit grayscale data can -be modified with png_set_filler(), png_set_add_alpha(), png_set_strip_16(), -or png_set_scale_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 -transparency information in a tRNS chunk. This is most useful on -grayscale images with bit depths of 2 or 4 or if there is a multiple-image -viewing application that wishes to treat all images in the same way. - - if (color_type == PNG_COLOR_TYPE_PALETTE) - png_set_palette_to_rgb(png_ptr); - - if (png_get_valid(png_ptr, info_ptr, - PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr); - - if (color_type == PNG_COLOR_TYPE_GRAY && - bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr); - -The first two functions are actually aliases for png_set_expand(), added -in libpng version 1.0.4, with the function names expanded to improve code -readability. In some future version they may actually do different -things. - -As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was -added. It expands the sample depth without changing tRNS to alpha. - -As of libpng version 1.5.2, png_set_expand_16() was added. It behaves as -png_set_expand(); however, the resultant channels have 16 bits rather than 8. -Use this when the output color or gray channels are made linear to avoid fairly -severe accuracy loss. - - if (bit_depth < 16) - png_set_expand_16(png_ptr); - -PNG can have files with 16 bits per channel. If you only can handle -8 bits per channel, this will strip the pixels down to 8-bit. - - if (bit_depth == 16) -#if PNG_LIBPNG_VER >= 10504 - png_set_scale_16(png_ptr); -#else - png_set_strip_16(png_ptr); -#endif - -(The more accurate "png_set_scale_16()" API became available in libpng version -1.5.4). - -If you need to process the alpha channel on the image separately from the image -data (for example if you convert it to a bitmap mask) it is possible to have -libpng strip the channel leaving just RGB or gray data: - - if (color_type & PNG_COLOR_MASK_ALPHA) - png_set_strip_alpha(png_ptr); - -If you strip the alpha channel you need to find some other way of dealing with -the information. If, instead, you want to convert the image to an opaque -version with no alpha channel use png_set_background; see below. - -As of libpng version 1.5.2, almost all useful expansions are supported, the -major ommissions are conversion of grayscale to indexed images (which can be -done trivially in the application) and conversion of indexed to grayscale (which -can be done by a trivial manipulation of the palette.) - -In the following table, the 01 means grayscale with depth<8, 31 means -indexed with depth<8, other numerals represent the color type, "T" means -the tRNS chunk is present, A means an alpha channel is present, and O -means tRNS or alpha is present but all pixels in the image are opaque. - - FROM 01 31 0 0T 0O 2 2T 2O 3 3T 3O 4A 4O 6A 6O - TO - 01 - [G] - - - - - - - - - - - - - - 31 [Q] Q [Q] [Q] [Q] Q Q Q Q Q Q [Q] [Q] Q Q - 0 1 G + . . G G G G G G B B GB GB - 0T lt Gt t + . Gt G G Gt G G Bt Bt GBt GBt - 0O lt Gt t . + Gt Gt G Gt Gt G Bt Bt GBt GBt - 2 C P C C C + . . C - - CB CB B B - 2T Ct - Ct C C t + t - - - CBt CBt Bt Bt - 2O Ct - Ct C C t t + - - - CBt CBt Bt Bt - 3 [Q] p [Q] [Q] [Q] Q Q Q + . . [Q] [Q] Q Q - 3T [Qt] p [Qt][Q] [Q] Qt Qt Qt t + t [Qt][Qt] Qt Qt - 3O [Qt] p [Qt][Q] [Q] Qt Qt Qt t t + [Qt][Qt] Qt Qt - 4A lA G A T T GA GT GT GA GT GT + BA G GBA - 4O lA GBA A T T GA GT GT GA GT GT BA + GBA G - 6A CA PA CA C C A T tT PA P P C CBA + BA - 6O CA PBA CA C C A tT T PA P P CBA C BA + - -Within the matrix, - "+" identifies entries where 'from' and 'to' are the same. - "-" means the transformation is not supported. - "." means nothing is necessary (a tRNS chunk can just be ignored). - "t" means the transformation is obtained by png_set_tRNS. - "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). - "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(). - -When an entry has multiple transforms listed all are required to cause the -right overall transformation. When two transforms are separated by a comma -either will do the job. When transforms are enclosed in [] the transform should -do the job but this is currently unimplemented - a different format will result -if the suggested transformations are used. - -In PNG files, the alpha channel in an image -is the level of opacity. If you need the alpha channel in an image to -be the level of transparency instead of opacity, you can invert the -alpha channel (or the tRNS chunk data) after it's read, so that 0 is -fully opaque and 255 (in 8-bit or paletted images) or 65535 (in 16-bit -images) is fully transparent, with - - png_set_invert_alpha(png_ptr); - -PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as -they can, resulting in, for example, 8 pixels per byte for 1 bit -files. This code expands to 1 pixel per byte without changing the -values of the pixels: - - if (bit_depth < 8) - png_set_packing(png_ptr); - -PNG files have possible bit depths of 1, 2, 4, 8, and 16. All pixels -stored in a PNG image have been "scaled" or "shifted" up to the next -higher possible bit depth (e.g. from 5 bits/sample in the range [0,31] -to 8 bits/sample in the range [0, 255]). However, it is also possible -to convert the PNG pixel data back to the original bit depth of the -image. This call reduces the pixels back down to the original bit depth: - - png_color_8p sig_bit; - - if (png_get_sBIT(png_ptr, info_ptr, &sig_bit)) - png_set_shift(png_ptr, sig_bit); - -PNG files store 3-color pixels in red, green, blue order. This code -changes the storage of the pixels to blue, green, red: - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_bgr(png_ptr); - -PNG files store RGB pixels packed into 3 or 6 bytes. This code expands them -into 4 or 8 bytes for windowing systems that need them in this format: - - if (color_type == PNG_COLOR_TYPE_RGB) - png_set_filler(png_ptr, filler, PNG_FILLER_BEFORE); - -where "filler" is the 8-bit 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. When filling an 8-bit pixel, -the least significant 8 bits of the number are used, if a 16-bit number is -supplied. This transformation does not affect images that already have full -alpha channels. To add an opaque alpha channel, use filler=0xffff and -PNG_FILLER_AFTER which will generate RGBA pixels. - -Note that png_set_filler() does not change the color type. If you want -to do that, you can add a true alpha channel with - - if (color_type == PNG_COLOR_TYPE_RGB || - color_type == PNG_COLOR_TYPE_GRAY) - png_set_add_alpha(png_ptr, filler, PNG_FILLER_AFTER); - -where "filler" contains the alpha value to assign to each pixel. -The png_set_add_alpha() function was added in libpng-1.2.7. - -If you are reading an image with an alpha channel, and you need the -data as ARGB instead of the normal PNG format RGBA: - - if (color_type == PNG_COLOR_TYPE_RGB_ALPHA) - png_set_swap_alpha(png_ptr); - -For some uses, you may want a grayscale image to be represented as -RGB. This code will do that conversion: - - if (color_type == PNG_COLOR_TYPE_GRAY || - 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. - - 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); - - 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 - - green_weight: weight of green component - If either weight is negative, default - weights are used. - -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_fixed_point green_weight); - -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. Background and sBIT data -will be silently converted to grayscale, using the green channel -data for sBIT, regardless of the error_action setting. - -The default values come from the PNG file cHRM chunk if present; otherwise, the -defaults correspond to the ITU-R recommendation 709, and also the sRGB color -space, as recommended in the Charles Poynton's Colour FAQ, -Copyright (c) 2006-11-28 Charles Poynton, in section 9: - - - - Y = 0.2126 * R + 0.7152 * G + 0.0722 * B - -Previous versions of this document, 1998 through 2002, recommended a slightly -different formula: - - Y = 0.212671 * R + 0.715160 * G + 0.072169 * B - -Libpng uses an integer approximation: - - Y = (6968 * R + 23434 * G + 2366 * B)/32768 - -The calculation is done in a linear colorspace, if the image gamma -can be determined. - -The png_set_background() function has been described already; it tells libpng to -composite images with alpha or simple transparency against the supplied -background color. For compatibility with versions of libpng earlier than -libpng-1.5.4 it is recommended that you call the function after reading the file -header, even if you don't want to use the color in a bKGD chunk, if one exists. - -If the PNG file contains a bKGD chunk (PNG_INFO_bKGD valid), -you may use this color, or supply another color more suitable for -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 -useful: - - 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/*needs to be expanded*/, 1); - else - png_set_background(png_ptr, &my_background, - PNG_BACKGROUND_GAMMA_SCREEN, 0/*do not expand*/, 1); - -The second call was described above - my_background is in the format of the -final, display, output produced by libpng. Because you now know the format of -the PNG it is possible to avoid the need to choose either 8-bit or 16-bit -output and to retain palette images (the palette colors will be modified -appropriately and the tRNS chunk removed.) However, if you are doing this, -take great care not to ask for transformations without checking first that -they apply! - -In the first call the background color has the original bit depth and color type -of the PNG file. So, for palette images the color is supplied as a palette -index and for low bit greyscale images the color is a reduced bit value in -image_background->gray. - -If you didn't call png_set_gamma() before reading the file header, for example -if you need your code to remain compatible with older versions of libpng prior -to libpng-1.5.4, this is the place to call it. - -Do not call it if you called png_set_alpha_mode(); doing so will damage the -settings put in place by png_set_alpha_mode(). (If png_set_alpha_mode() is -supported then you can certainly do png_set_gamma() before reading the PNG -header.) - -This API unconditionally sets the screen and file gamma values, so it will -override the value in the PNG file unless it is called before the PNG file -reading starts. For this reason you must always call it with the PNG file -value when you call it in this position: - - if (png_get_gAMA(png_ptr, info_ptr, &file_gamma)) - png_set_gamma(png_ptr, screen_gamma, file_gamma); - - else - 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 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 -pass a palette that is larger than maximum_colors, the file will -reduce the number of colors in the palette so it will fit into -maximum_colors. If there is a histogram, libpng will use it to make -more intelligent choices when reducing the palette. If there is no -histogram, it may not do as good a job. - - if (color_type & PNG_COLOR_MASK_COLOR) - { - if (png_get_valid(png_ptr, info_ptr, - PNG_INFO_PLTE)) - { - png_uint_16p histogram = NULL; - - png_get_hIST(png_ptr, info_ptr, - &histogram); - png_set_quantize(png_ptr, palette, num_palette, - max_screen_colors, histogram, 1); - } - - else - { - png_color std_color_cube[MAX_SCREEN_COLORS] = - { ... colors ... }; - - png_set_quantize(png_ptr, std_color_cube, - MAX_SCREEN_COLORS, MAX_SCREEN_COLORS, - NULL,0); - } - } - -PNG files describe monochrome as black being zero and white being one. -The following code will reverse this (make black be one and white be -zero): - - if (bit_depth == 1 && color_type == PNG_COLOR_TYPE_GRAY) - png_set_invert_mono(png_ptr); - -This function can also be used to invert grayscale and gray-alpha images: - - if (color_type == PNG_COLOR_TYPE_GRAY || - color_type == PNG_COLOR_TYPE_GRAY_ALPHA) - png_set_invert_mono(png_ptr); - -PNG files store 16-bit pixels in network byte order (big-endian, -ie. most significant bits first). This code changes the storage to the -other way (little-endian, i.e. least significant bits first, the -way PCs store them): - - if (bit_depth == 16) - png_set_swap(png_ptr); - -If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you -need to change the order the pixels are packed into bytes, you can use: - - if (bit_depth < 8) - png_set_packswap(png_ptr); - -Finally, you can write your own transformation function if none of -the existing ones meets your needs. This is done by setting a callback -with - - png_set_read_user_transform_fn(png_ptr, - read_transform_fn); - -You must supply the function - - void read_transform_fn(png_structp png_ptr, png_row_infop - 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. Take care with -interlaced images if you do the interlace yourself - the width of the row is the -width in 'row_info', not the overall image width. - -If supported, libpng provides two information routines that you can use to find -where you are in processing the image: - - png_get_current_pass_number(png_structp png_ptr); - png_get_current_row_number(png_structp png_ptr); - -Don't try using these outside a transform callback - firstly they are only -supported if user transforms are supported, secondly they may well return -unexpected results unless the row is actually being processed at the moment they -are called. - -With interlaced -images the value returned is the row in the input sub-image image. Use -PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to -find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass). - -The discussion of interlace handling above contains more information on how to -use these values. - -You can also set up a pointer to a user structure for use by your -callback function, and you can inform libpng that your transform -function will change the number of channels or bit depth with the -function - - png_set_user_transform_info(png_ptr, user_ptr, - user_depth, user_channels); - -The user's application, not libpng, is responsible for allocating and -freeing any memory required for the user structure. - -You can retrieve the pointer via the function -png_get_user_transform_ptr(). For example: - - voidp read_user_transform_ptr = - png_get_user_transform_ptr(png_ptr); - -The last thing to handle is interlacing; this is covered in detail below, -but you must call the function here if you want libpng to handle expansion -of the interlaced image. - - number_of_passes = png_set_interlace_handling(png_ptr); - -After setting the transformations, libpng can update your png_info -structure to reflect any transformations you've requested with this -call. - - png_read_update_info(png_ptr, info_ptr); - -This is most useful to update the info structure's rowbytes -field so you can use it to allocate your image memory. This function -will also update your palette with the correct screen_gamma and -background if these have been given with the calls above. You may -only call png_read_update_info() once with a particular info_ptr. - -After you call png_read_update_info(), you can allocate any -memory you need to hold the image. The row data is simply -raw byte data for all forms of images. As the actual allocation -varies among applications, no example will be given. If you -are allocating one large chunk, you will need to build an -array of pointers to each row, as it will be needed for some -of the functions below. - -Be sure that your platform can allocate the buffer that you'll need. -libpng internally checks for oversize width, but you'll need to -do your own check for number_of_rows*width*pixel_size if you are using -a multiple-row buffer: - - /* Guard against integer overflow */ - if (number_of_rows > PNG_SIZE_MAX/(width*pixel_size)) { - png_error(png_ptr,"image_data buffer would be too large"); - } - -Remember: Before you call png_read_update_info(), the png_get_*() -functions return the values corresponding to the original PNG image. -After you call png_read_update_info the values refer to the image -that libpng will output. Consequently you must call all the png_set_ -functions before you call png_read_update_info(). This is particularly -important for png_set_interlace_handling() - if you are going to call -png_read_update_info() you must call png_set_interlace_handling() before -it unless you want to receive interlaced output. - -Reading image data - -After you've allocated memory, you can read the image data. -The simplest way to do this is in one function call. If you are -allocating enough memory to hold the whole image, you can just -call png_read_image() and libpng will read in all the image data -and put it in the memory area supplied. You will need to pass in -an array of pointers to each row. - -This function automatically handles interlacing, so you don't -need to call png_set_interlace_handling() (unless you call -png_read_update_info()) or call this function multiple times, or any -of that other stuff necessary with png_read_rows(). - - png_read_image(png_ptr, row_pointers); - -where row_pointers is: - - png_bytep row_pointers[height]; - -You can point to void or char or whatever you use for pixels. - -If you don't want to read in the whole image at once, you can -use png_read_rows() instead. If there is no interlacing (check -interlace_type == PNG_INTERLACE_NONE), this is simple: - - png_read_rows(png_ptr, row_pointers, NULL, - number_of_rows); - -where row_pointers is the same as in the png_read_image() call. - -If you are doing this just one row at a time, you can do this with -a single row_pointer instead of an array of row_pointers: - - png_bytep row_pointer = row; - png_read_row(png_ptr, row_pointer, NULL); - -If the file is interlaced (interlace_type != 0 in the IHDR chunk), things -get somewhat harder. The only current (PNG Specification version 1.2) -interlacing type for PNG is (interlace_type == PNG_INTERLACE_ADAM7); -a somewhat complicated 2D interlace scheme, known as Adam7, that -breaks down an image into seven smaller images of varying size, based -on an 8x8 grid. This number is defined (from libpng 1.5) as -PNG_INTERLACE_ADAM7_PASSES in png.h - -libpng can fill out those images or it can give them to you "as is". -It is almost always better to have libpng handle the interlacing for you. -If you want the images filled out, there are two ways to do that. The one -mentioned in the PNG specification is to expand each pixel to cover -those pixels that have not been read yet (the "rectangle" method). -This results in a blocky image for the first pass, which gradually -smooths out as more pixels are read. The other method is the "sparkle" -method, where pixels are drawn only in their final locations, with the -rest of the image remaining whatever colors they were initialized to -before the start of the read. The first method usually looks better, -but tends to be slower, as there are more pixels to put in the rows. - -If, as is likely, you want libpng to expand the images, call this before -calling png_start_read_image() or png_read_update_info(): - - if (interlace_type == PNG_INTERLACE_ADAM7) - number_of_passes - = png_set_interlace_handling(png_ptr); - -This will return the number of passes needed. Currently, this is seven, -but may change if another interlace type is added. This function can be -called even if the file is not interlaced, where it will return one pass. -You then need to read the whole image 'number_of_passes' times. Each time -will distribute the pixels from the current pass to the correct place in -the output image, so you need to supply the same rows to png_read_rows in -each pass. - -If you are not going to display the image after each pass, but are -going to wait until the entire image is read in, use the sparkle -effect. This effect is faster and the end result of either method -is exactly the same. If you are planning on displaying the image -after each pass, the "rectangle" effect is generally considered the -better looking one. - -If you only want the "sparkle" effect, just call png_read_row() or -png_read_rows() as -normal, with the third parameter NULL. Make sure you make pass over -the image number_of_passes times, and you don't change the data in the -rows between calls. You can change the locations of the data, just -not the data. Each pass only writes the pixels appropriate for that -pass, and assumes the data from previous passes is still valid. - - png_read_rows(png_ptr, row_pointers, NULL, - number_of_rows); - or - png_read_row(png_ptr, row_pointers, NULL); - -If you only want the first effect (the rectangles), do the same as -before except pass the row buffer in the third parameter, and leave -the second parameter NULL. - - png_read_rows(png_ptr, NULL, row_pointers, - number_of_rows); - or - png_read_row(png_ptr, NULL, row_pointers); - -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 -certainly need to distribute the pixels from each sub-image to the -correct place. This is where everything gets very tricky. - -If you want to retrieve the separate images you must pass the correct -number of rows to each successive call of png_read_rows(). The calculation -gets pretty complicated for small images, where some sub-images may -not even exist because either their width or height ends up zero. -libpng provides two macros to help you in 1.5 and later versions: - - png_uint_32 width = PNG_PASS_COLS(image_width, pass_number); - png_uint_32 height = PNG_PASS_ROWS(image_height, pass_number); - -Respectively these tell you the width and height of the sub-image -corresponding to the numbered pass. 'pass' is in in the range 0 to 6 - -this can be confusing because the specification refers to the same passes -as 1 to 7! Be careful, you must check both the width and height before -calling png_read_rows() and not call it for that pass if either is zero. - -You can, of course, read each sub-image row by row. If you want to -produce optimal code to make a pixel-by-pixel transformation of an -interlaced image this is the best approach; read each row of each pass, -transform it, and write it out to a new interlaced image. - -If you want to de-interlace the image yourself libpng provides further -macros to help that tell you where to place the pixels in the output image. -Because the interlacing scheme is rectangular - sub-image pixels are always -arranged on a rectangular grid - all you need to know for each pass is the -starting column and row in the output image of the first pixel plus the -spacing between each pixel. As of libpng 1.5 there are four macros to -retrieve this information: - - png_uint_32 x = PNG_PASS_START_COL(pass); - png_uint_32 y = PNG_PASS_START_ROW(pass); - png_uint_32 xStep = 1U << PNG_PASS_COL_SHIFT(pass); - png_uint_32 yStep = 1U << PNG_PASS_ROW_SHIFT(pass); - -These allow you to write the obvious loop: - - png_uint_32 input_y = 0; - png_uint_32 output_y = PNG_PASS_START_ROW(pass); - - while (output_y < output_image_height) - { - png_uint_32 input_x = 0; - png_uint_32 output_x = PNG_PASS_START_COL(pass); - - while (output_x < output_image_width) - { - image[output_y][output_x] = - subimage[pass][input_y][input_x++]; - - output_x += xStep; - } - - ++input_y; - output_y += yStep; - } - -Notice that the steps between successive output rows and columns are -returned as shifts. This is possible because the pixels in the subimages -are always a power of 2 apart - 1, 2, 4 or 8 pixels - in the original -image. In practice you may need to directly calculate the output coordinate -given an input coordinate. libpng provides two further macros for this -purpose: - - png_uint_32 output_x = PNG_COL_FROM_PASS_COL(input_x, pass); - png_uint_32 output_y = PNG_ROW_FROM_PASS_ROW(input_y, pass); - -Finally a pair of macros are provided to tell you if a particular image -row or column appears in a given pass: - - int col_in_pass = PNG_COL_IN_INTERLACE_PASS(output_x, pass); - int row_in_pass = PNG_ROW_IN_INTERLACE_PASS(output_y, pass); - -Bear in mind that you will probably also need to check the width and height -of the pass in addition to the above to be sure the pass even exists! - -With any luck you are convinced by now that you don't want to do your own -interlace handling. In reality normally the only good reason for doing this -is if you are processing PNG files on a pixel-by-pixel basis and don't want -to load the whole file into memory when it is interlaced. - -libpng includes a test program, pngvalid, that illustrates reading and -writing of interlaced images. If you can't get interlacing to work in your -code and don't want to leave it to libpng (the recommended approach), see -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 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); - - if (!end_info) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - png_read_end(png_ptr, end_info); - -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); - -If you don't call png_read_end(), then your file pointer will be -left pointing to the first chunk after the last IDAT, which is probably -not what you want if you expect to read something beyond the end of -the PNG datastream. - -When you are done, you can free all memory allocated by libpng like this: - - png_destroy_read_struct(&png_ptr, &info_ptr, - &end_info); - -or, if you didn't create an end_info structure, - - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - -It is also possible to individually free the info_ptr members that -point to libpng-allocated storage with the following function: - - png_free_data(png_ptr, info_ptr, mask, seq) - - mask - identifies data to be freed, a mask - containing the bitwise OR of one or - more of - PNG_FREE_PLTE, PNG_FREE_TRNS, - PNG_FREE_HIST, PNG_FREE_ICCP, - PNG_FREE_PCAL, PNG_FREE_ROWS, - PNG_FREE_SCAL, PNG_FREE_SPLT, - PNG_FREE_TEXT, PNG_FREE_UNKN, - or simply PNG_FREE_ALL - - seq - sequence number of item to be freed - (-1 for all items) - -This function may be safely called when the relevant storage has -already been freed, or has not yet been allocated, or was allocated -by the user and not by libpng, and will in those cases do nothing. -The "seq" parameter is ignored if only one item of the selected data -type, such as PLTE, is allowed. If "seq" is not -1, and multiple items -are allowed for the data type identified in the mask, such as text or -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_calloc() and passed in via a png_set_*() function, with - - png_data_freer(png_ptr, info_ptr, freer, mask) - - freer - one of - PNG_DESTROY_WILL_FREE_DATA - PNG_SET_WILL_FREE_DATA - PNG_USER_WILL_FREE_DATA - - mask - which data elements are affected - same choices as in png_free_data() - -This function only affects data that has already been allocated. -You can call this function after reading the PNG data but before calling -any png_set_*() functions, to control whether the user or the png_set_*() -function is responsible for freeing any existing data that might be present, -and again after the png_set_*() functions to control whether the user -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_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 -responsibility for freeing it to the png_set_rows or png_read_destroy function, -because they would also try to free the individual row_pointers[i]. - -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, -because when libpng fills a png_text structure it combines these members with -the key member, and png_free_data() will free only text_ptr.key. Similarly, -if you transfer responsibility for free'ing text_ptr from libpng to your -application, your application must not separately free those members. - -The png_free_data() function will turn off the "valid" flag for anything -it frees. If you need to turn the flag off for a chunk that was freed by -your application instead of by libpng, you can use - - png_set_invalid(png_ptr, info_ptr, mask); - - mask - identifies the chunks to be made invalid, - containing the bitwise OR of one or - more of - PNG_INFO_gAMA, PNG_INFO_sBIT, - PNG_INFO_cHRM, PNG_INFO_PLTE, - PNG_INFO_tRNS, PNG_INFO_bKGD, - PNG_INFO_eXIf, - PNG_INFO_hIST, PNG_INFO_pHYs, - PNG_INFO_oFFs, PNG_INFO_tIME, - PNG_INFO_pCAL, PNG_INFO_sRGB, - PNG_INFO_iCCP, PNG_INFO_sPLT, - PNG_INFO_sCAL, PNG_INFO_IDAT - -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 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 -set up these callbacks with png_set_progressive_read_fn(). You don't -have to worry about the input/output functions of libpng, as you are -giving the library the data directly in png_process_data(). I will -assume that you have read the section on reading PNG files above, -so I will only highlight the differences (although I will show -all of the code). - -png_structp png_ptr; -png_infop info_ptr; - - /* An example code fragment of how you would - initialize the progressive reader in your - application. */ - int - initialize_png_reader() - { - png_ptr = png_create_read_struct - (PNG_LIBPNG_VER_STRING, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - - if (!png_ptr) - return (ERROR); - - info_ptr = png_create_info_struct(png_ptr); - - if (!info_ptr) - { - png_destroy_read_struct(&png_ptr, - (png_infopp)NULL, (png_infopp)NULL); - return (ERROR); - } - - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - /* This one's new. You can provide functions - 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 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 - - png_get_progressive_ptr(png_ptr); - - which will return a void pointer, which you have - to cast appropriately. - */ - png_set_progressive_read_fn(png_ptr, (void *)user_ptr, - info_callback, row_callback, end_callback); - - return 0; - } - - /* A code fragment that you call as you receive blocks - of data */ - int - process_data(png_bytep buffer, png_uint_32 length) - { - if (setjmp(png_jmpbuf(png_ptr))) - { - png_destroy_read_struct(&png_ptr, &info_ptr, - (png_infopp)NULL); - return (ERROR); - } - - /* This one's new also. Simply give it a chunk - 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 - 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 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 - so there. - */ - png_process_data(png_ptr, info_ptr, buffer, length); - - /* At this point you can call png_process_data_skip if - you want to handle data the library will skip yourself; - it simply returns the number of bytes to skip (and stops - libpng skipping that number of bytes on the next - png_process_data call). - return 0; - } - - /* This function is called (as set by - png_set_progressive_read_fn() above) when enough data - has been supplied so all of the header has been - read. - */ - void - info_callback(png_structp png_ptr, png_infop info) - { - /* Do any setup here, including setting any of - the transformations mentioned in the Reading - PNG files section. For now, you _must_ call - either png_start_read_image() or - png_read_update_info() after all the - transformations are set (even if you don't set - any). You may start getting rows before - png_process_data() returns, so this is your - last chance to prepare for that. - - This is where you turn on interlace handling, - assuming you don't want to do it yourself. - - If you need to you can stop the processing of - your original input data at this point by calling - png_process_data_pause. This returns the number - of unprocessed bytes from the last png_process_data - call - it is up to you to ensure that the next call - sees these bytes again. If you don't want to bother - with this you can get libpng to cache the unread - bytes by setting the 'save' parameter (see png.h) but - then libpng will have to copy the data internally. - */ - } - - /* This function is called when each row of image - data is complete */ - void - row_callback(png_structp png_ptr, png_bytep new_row, - png_uint_32 row_num, int pass) - { - /* If the image is interlaced, and you turned - on the interlace handler, this function will - be called for every row in every pass. Some - of these rows will not be changed from the - previous pass. When the row is not changed, - the new_row variable will be NULL. The rows - and passes are called in order, so you don't - really need the row_num and pass, but I'm - supplying them because it may make your life - easier. - - If you did not turn on interlace handling then - the callback is called for each row of each - sub-image when the image is interlaced. In this - case 'row_num' is the row in the sub-image, not - the row in the output image as it is in all other - cases. - - For the non-NULL rows of interlaced images when - you have switched on libpng interlace handling, - you must call png_progressive_combine_row() - passing in the row and the old row. You can - call this function for NULL rows (it will just - return) and for non-interlaced images (it just - does the memcpy for you) if it will make the - code easier. Thus, you can just do this for - all cases if you switch on interlace handling; - */ - - png_progressive_combine_row(png_ptr, old_row, - new_row); - - /* 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 - 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. - - You can also call png_process_data_pause in this - callback - see above. - */ - } - - void - end_callback(png_structp png_ptr, png_infop info) - { - /* This function is called after the whole image - has been read, including any chunks after the - image (up to and including the IEND). You - will usually have the same info chunk as you - had in the header, although some data may have - been added to the comments and time fields. - - Most people won't do much here, perhaps setting - a flag that marks the image as finished. - */ - } - - - -IV. Writing - -Much of this is very similar to reading. However, everything of -importance is repeated here, so you won't have to constantly look -back up in the reading section to understand writing. - -Setup - -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) - return (ERROR); - -Next, png_struct and png_info need to be allocated and initialized. -As these can be both relatively large, you may not want to store these -on the stack, unless you have stack space to spare. Of course, you -will want to check if they return NULL. If you are also reading, -you won't want to name your read structure and your write structure -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, (png_voidp)user_error_ptr, - user_error_fn, user_warning_fn); - - if (!png_ptr) - return (ERROR); - - png_infop info_ptr = png_create_info_struct(png_ptr); - if (!info_ptr) - { - png_destroy_write_struct(&png_ptr, - (png_infopp)NULL); - return (ERROR); - } - -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_write_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 png_jmpbuf(png_ptr). If you -write the file from different routines, you will need to update -the png_jmpbuf(png_ptr) 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_jmpbuf(png_ptr))) - { - png_destroy_write_struct(&png_ptr, &info_ptr); - fclose(fp); - return (ERROR); - } - ... - return; - -If you would rather avoid the complexity of setjmp/longjmp issues, -you can compile libpng with PNG_NO_SETJMP, in which case -errors will result in a call to PNG_ABORT() which defaults to abort(). - -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 -opened in binary mode. Again, if you wish to handle writing data in -another way, see the discussion on libpng I/O handling in the Customizing -Libpng section below. - - png_init_io(png_ptr, fp); - -If you are embedding your PNG into a datastream such as MNG, and don't -want libpng to write the 8-byte signature, or if you have already -written the signature in your application, use - - png_set_sig_bytes(png_ptr, 8); - -to inform libpng that it should not write a signature. - -Write callbacks - -At this point, you can set up a callback function that will be -called after each row has been written, which you can use to control -a progress meter or the like. It's demonstrated in pngtest.c. -You must supply a function - - void write_row_callback(png_structp png_ptr, png_uint_32 row, - int pass); - { - /* put your code here */ - } - -(You can give it another name that you like instead of "write_row_callback") - -To inform libpng about your function, use - - png_set_write_status_fn(png_ptr, write_row_callback); - -When this function is called the row has already been completely processed and -it has also been written out. The 'row' and 'pass' refer to the next row to be -handled. For the -non-interlaced case the row that was just handled is simply one less than the -passed in row number, and pass will always be 0. For the interlaced case the -same applies unless the row value is 0, in which case the row just handled was -the last one from one of the preceding passes. Because interlacing may skip a -pass you cannot be sure that the preceding pass is just 'pass-1', if you really -need to know what the last pass is record (row,pass) from the callback and use -the last recorded value each time. - -As with the user transform you can find the output row using the -PNG_ROW_FROM_PASS_ROW macro. - -You now have the option of modifying how the compression library will -run. The following functions are mainly for testing, but may be useful -in some cases, like if you need to write PNG files extremely fast and -are willing to give up some compression, or if you want to get the -maximum possible compression at the expense of slower writing. If you -have no special needs in this area, let the library do what it wants by -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 values are 0 (as of the -July 1999 PNG specification, version 1.2) or 64 (if you are writing -a PNG datastream that is to be embedded in a MNG datastream). The third -parameter is a flag that indicates which filter type(s) are to be tested -for each scanline. See the PNG specification for details on the specific -filter types. - - - /* turn on or off filtering, and/or choose - specific filters. You can use either a single - PNG_FILTER_VALUE_NAME or the bitwise OR of one - or more PNG_FILTER_NAME masks. - */ - png_set_filter(png_ptr, 0, - PNG_FILTER_NONE | PNG_FILTER_VALUE_NONE | - PNG_FILTER_SUB | PNG_FILTER_VALUE_SUB | - PNG_FILTER_UP | PNG_FILTER_VALUE_UP | - PNG_FILTER_AVG | PNG_FILTER_VALUE_AVG | - PNG_FILTER_PAETH | PNG_FILTER_VALUE_PAETH| - PNG_ALL_FILTERS | PNG_FAST_FILTERS); - -If an application wants to start and stop using particular filters during -compression, it should start out with all of the filters (to ensure that -the previous row of pixels will be stored in case it's needed later), -and then add and remove them after the start of compression. - -If you are writing a PNG datastream that is to be embedded in a MNG -datastream, the second parameter can be either 0 or 64. - -The png_set_compression_*() functions interface to the zlib compression -library, and should mostly be ignored unless you really know what you are -doing. The only generally useful call is png_set_compression_level() -which changes how much time zlib spends on trying to compress the image -data. See the Compression Library (zlib.h and algorithm.txt, distributed -with zlib) for details on the compression levels. - - #include zlib.h - - /* Set the zlib compression level */ - png_set_compression_level(png_ptr, - Z_BEST_COMPRESSION); - - /* Set other zlib parameters for compressing IDAT */ - png_set_compression_mem_level(png_ptr, 8); - png_set_compression_strategy(png_ptr, - Z_DEFAULT_STRATEGY); - png_set_compression_window_bits(png_ptr, 15); - png_set_compression_method(png_ptr, 8); - png_set_compression_buffer_size(png_ptr, 8192) - - /* Set zlib parameters for text compression - * If you don't call these, the parameters - * fall back on those defined for IDAT chunks - */ - png_set_text_compression_mem_level(png_ptr, 8); - png_set_text_compression_strategy(png_ptr, - Z_DEFAULT_STRATEGY); - png_set_text_compression_window_bits(png_ptr, 15); - png_set_text_compression_method(png_ptr, 8); - -Setting the contents of info for output - -You now need to fill in the png_info structure with all the data you -wish to write before the actual image. Note that the only thing you -are allowed to write after the image is the text chunks and the time -chunk (as of PNG Specification 1.2, anyway). See png_write_end() and -the latest PNG specification for more information on that. If you -wish to write them before the image, fill them in now, and flag that -data as being valid. If you want to wait until after the data, don't -fill them until png_write_end(). For all the fields in png_info and -their data types, see png.h. For explanations of what the fields -contain, see the PNG specification. - -Some of the more important parts of the png_info are: - - png_set_IHDR(png_ptr, info_ptr, width, height, - bit_depth, color_type, interlace_type, - compression_type, filter_method) - - width - holds the width of the image - in pixels (up to 2^31). - - height - holds the height of the image - in pixels (up to 2^31). - - bit_depth - holds the bit depth of one of the - image channels. - (valid values are 1, 2, 4, 8, 16 - and depend also on the - color_type. See also significant - bits (sBIT) below). - - color_type - describes which color/alpha - channels are present. - PNG_COLOR_TYPE_GRAY - (bit depths 1, 2, 4, 8, 16) - PNG_COLOR_TYPE_GRAY_ALPHA - (bit depths 8, 16) - PNG_COLOR_TYPE_PALETTE - (bit depths 1, 2, 4, 8) - PNG_COLOR_TYPE_RGB - (bit_depths 8, 16) - PNG_COLOR_TYPE_RGB_ALPHA - (bit_depths 8, 16) - - PNG_COLOR_MASK_PALETTE - PNG_COLOR_MASK_COLOR - PNG_COLOR_MASK_ALPHA - - interlace_type - PNG_INTERLACE_NONE or - PNG_INTERLACE_ADAM7 - - compression_type - (must be - PNG_COMPRESSION_TYPE_DEFAULT) - - filter_method - (must be PNG_FILTER_TYPE_DEFAULT - or, if you are writing a PNG to - be embedded in a MNG datastream, - can also be - PNG_INTRAPIXEL_DIFFERENCING) - -If you call png_set_IHDR(), the call must appear before any of the -other png_set_*() functions, because they might require access to some of -the IHDR settings. The remaining png_set_*() functions can be called -in any order. - -If you wish, you can reset the compression_type, interlace_type, or -filter_method later by calling png_set_IHDR() again; if you do this, the -width, height, bit_depth, and color_type must be the same in each call. - - png_set_PLTE(png_ptr, info_ptr, palette, - num_palette); - - palette - the palette for the file - (array of png_color) - num_palette - number of entries in the palette - - - png_set_gAMA(png_ptr, info_ptr, file_gamma); - png_set_gAMA_fixed(png_ptr, info_ptr, int_file_gamma); - - file_gamma - the gamma at which the image was - created (PNG_INFO_gAMA) - - int_file_gamma - 100,000 times the gamma at which - the image was created - - png_set_cHRM(png_ptr, info_ptr, white_x, white_y, red_x, red_y, - green_x, green_y, blue_x, blue_y) - png_set_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_set_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_set_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) - - {white,red,green,blue}_{x,y} - A color space encoding specified using the chromaticities - of the end points and the white point. - - {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_set_sRGB(png_ptr, info_ptr, srgb_intent); - - 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 implies specific - values of gAMA and cHRM. Rendering - intent is the CSS-1 property that - has been defined by the International - Color Consortium - (http://www.color.org). - It can be one of - PNG_sRGB_INTENT_SATURATION, - 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); - - 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 function also causes gAMA and - cHRM chunks with the specific values - that are consistent with sRGB to be - written. - - png_set_iCCP(png_ptr, info_ptr, name, compression_type, - profile, proflen); - - name - The profile name. - - compression_type - The compression type; always - PNG_COMPRESSION_TYPE_BASE for PNG 1.0. - You may give NULL to this argument to - ignore it. - - profile - International Color Consortium color - profile data. May contain NULs. - - proflen - length of profile data in bytes. - - png_set_sBIT(png_ptr, info_ptr, sig_bit); - - sig_bit - the number of significant bits for - (PNG_INFO_sBIT) each of the gray, red, - green, and blue channels, whichever are - appropriate for the given color type - (png_color_16) - - png_set_tRNS(png_ptr, info_ptr, trans_alpha, - num_trans, trans_color); - - trans_alpha - array of alpha (transparency) - entries for palette (PNG_INFO_tRNS) - - num_trans - number of transparent entries - (PNG_INFO_tRNS) - - trans_color - graylevel or color sample values - (in order red, green, blue) of the - single transparent color for - non-paletted images (PNG_INFO_tRNS) - - png_set_eXIf_1(png_ptr, info_ptr, num_exif, exif); - - exif - Exif profile (array of - png_byte) (PNG_INFO_eXIf) - - png_set_hIST(png_ptr, info_ptr, hist); - - hist - histogram of palette (array of - png_uint_16) (PNG_INFO_hIST) - - png_set_tIME(png_ptr, info_ptr, mod_time); - - mod_time - time image was last modified - (PNG_VALID_tIME) - - png_set_bKGD(png_ptr, info_ptr, background); - - background - background color (of type - png_color_16p) (PNG_VALID_bKGD) - - png_set_text(png_ptr, info_ptr, text_ptr, num_text); - - text_ptr - array of png_text holding image - comments - - text_ptr[i].compression - type of compression used - on "text" PNG_TEXT_COMPRESSION_NONE - PNG_TEXT_COMPRESSION_zTXt - PNG_ITXT_COMPRESSION_NONE - PNG_ITXT_COMPRESSION_zTXt - text_ptr[i].key - keyword for comment. Must contain - 1-79 characters. - text_ptr[i].text - text comments for current - keyword. Can be NULL or empty. - text_ptr[i].text_length - length of text string, - after decompression, 0 for iTXt - text_ptr[i].itxt_length - length of itxt string, - after decompression, 0 for tEXt/zTXt - text_ptr[i].lang - language of comment (NULL or - empty for unknown). - text_ptr[i].translated_keyword - keyword in UTF-8 (NULL - or empty for unknown). - - Note that the itxt_length, lang, and lang_key - members of the text_ptr structure only exist when the - library is built with iTXt chunk support. Prior to - libpng-1.4.0 the library was built by default without - iTXt support. Also note that when iTXt is supported, - they contain NULL pointers when the "compression" - field contains PNG_TEXT_COMPRESSION_NONE or - PNG_TEXT_COMPRESSION_zTXt. - - num_text - number of comments - - png_set_sPLT(png_ptr, info_ptr, &palette_ptr, - num_spalettes); - - palette_ptr - array of png_sPLT_struct structures - to be added to the list of palettes - in the info structure. - num_spalettes - number of palette structures to be - added. - - png_set_oFFs(png_ptr, info_ptr, offset_x, offset_y, - unit_type); - - offset_x - positive offset from the left - edge of the screen - - offset_y - positive offset from the top - edge of the screen - - unit_type - PNG_OFFSET_PIXEL, PNG_OFFSET_MICROMETER - - png_set_pHYs(png_ptr, info_ptr, res_x, res_y, - unit_type); - - res_x - pixels/unit physical resolution - in x direction - - res_y - pixels/unit physical resolution - in y direction - - unit_type - PNG_RESOLUTION_UNKNOWN, - PNG_RESOLUTION_METER - - png_set_sCAL(png_ptr, info_ptr, unit, width, height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - - height - height of a pixel in physical scale units - (width and height are doubles) - - png_set_sCAL_s(png_ptr, info_ptr, unit, width, height) - - unit - physical scale units (an integer) - - width - width of a pixel in physical scale units - expressed as a string - - height - height of a pixel in physical scale units - (width and height are strings like "2.54") - - png_set_unknown_chunks(png_ptr, info_ptr, &unknowns, - num_unknowns) - - unknowns - array of png_unknown_chunk - structures holding unknown chunks - unknowns[i].name - name of unknown chunk - unknowns[i].data - data of unknown chunk - unknowns[i].size - size of unknown chunk's data - unknowns[i].location - position to write chunk in file - 0: do not write chunk - PNG_HAVE_IHDR: before PLTE - PNG_HAVE_PLTE: before IDAT - PNG_AFTER_IDAT: after IDAT - -The "location" member is set automatically according to -what part of the output file has already been written. -You can change its value after calling png_set_unknown_chunks() -as demonstrated in pngtest.c. Within each of the "locations", -the chunks are sequenced according to their position in the -structure (that is, the value of "i", which is the order in which -the chunk was either read from the input file or defined with -png_set_unknown_chunks). - -A quick word about text and num_text. text is an array of png_text -structures. num_text is the number of valid structures in the array. -Each png_text structure holds a language code, a keyword, a 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 -text compressed, set the compression type to PNG_TEXT_COMPRESSION_NONE. -Because tEXt and zTXt chunks don't have a language field, if you -specify PNG_TEXT_COMPRESSION_NONE or PNG_TEXT_COMPRESSION_zTXt -any language code or translated keyword will not be written out. - -Until text gets around a few hundred bytes, it is not worth compressing it. -After the text has been written out to the file, the compression type -is set to PNG_TEXT_COMPRESSION_NONE_WR or PNG_TEXT_COMPRESSION_zTXt_WR, -so that it isn't written out again at the end (in case you are calling -png_write_end() with the same struct). - -The keywords that are given in the PNG Specification are: - - Title Short (one line) title or - caption for image - - Author Name of image's creator - - Description Description of image (possibly long) - - Copyright Copyright notice - - Creation Time Time of original image creation - (usually RFC 1123 format, see below) - - Software Software used to create the image - - Disclaimer Legal disclaimer - - Warning Warning of nature of content - - Source Device used to create the image - - Comment Miscellaneous comment; conversion - from other image format - -The keyword-text pairs work like this. Keywords should be short -simple descriptions of what the comment is about. Some typical -keywords are found in the PNG specification, as is some recommendations -on keywords. You can repeat keywords in a file. You can even write -some text before the image and some after. For example, you may want -to put a description of the image before the image, but leave the -disclaimer until after, so viewers working over modem connections -don't have to wait for the disclaimer to go over the modem before -they start seeing the image. Finally, keywords should be full -words, not abbreviations. Keywords and text are in the ISO 8859-1 -(Latin-1) character set (a superset of regular ASCII) and can not -contain NUL characters, and should not contain control or other -unprintable characters. To make the comments widely readable, stick -with basic ASCII, and avoid machine specific character set extensions -like the IBM-PC character set. The keyword must be present, but -you can leave off the text string on non-compressed pairs. -Compressed pairs must have a text string, as only the text string -is compressed anyway, so the compression would be meaningless. - -PNG supports modification time via the png_time structure. Two -conversion routines are provided, png_convert_from_time_t() for -time_t and png_convert_from_struct_tm() for struct tm. The -time_t routine uses gmtime(). You don't have to use either of -these, but if you wish to fill in the png_time structure directly, -you should provide the time in universal time (GMT) if possible -instead of your local time. Note that the year number is the full -year (e.g. 1998, rather than 98 - PNG is year 2000 compliant!), and -that months start with 1. - -If you want to store the time of the original image creation, you should -use a plain tEXt chunk with the "Creation Time" keyword. This is -necessary because the "creation time" of a PNG image is somewhat vague, -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"), -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_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 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 - -At this point there are two ways to proceed; through the high-level -write interface, or through a sequence of low-level write operations. -You can use the high-level interface if your image data is present -in the info structure. All defined output -transformations are permitted, enabled by the following masks. - - PNG_TRANSFORM_IDENTITY No transformation - PNG_TRANSFORM_PACKING Pack 1, 2 and 4-bit samples - PNG_TRANSFORM_PACKSWAP Change order of packed - pixels to LSB first - PNG_TRANSFORM_INVERT_MONO Invert monochrome images - PNG_TRANSFORM_SHIFT Normalize pixels to the - sBIT depth - PNG_TRANSFORM_BGR Flip RGB to BGR, RGBA - to BGRA - PNG_TRANSFORM_SWAP_ALPHA Flip RGBA to ARGB or GA - to AG - PNG_TRANSFORM_INVERT_ALPHA Change alpha from opacity - to transparency - PNG_TRANSFORM_SWAP_ENDIAN Byte-swap 16-bit samples - PNG_TRANSFORM_STRIP_FILLER Strip out filler - bytes (deprecated). - PNG_TRANSFORM_STRIP_FILLER_BEFORE Strip out leading - filler bytes - PNG_TRANSFORM_STRIP_FILLER_AFTER Strip out trailing - filler bytes - -If you have valid image data in the info structure (you can use -png_set_rows() to put image data in the info structure), simply do this: - - png_write_png(png_ptr, info_ptr, png_transforms, NULL) - -where png_transforms is an integer containing the bitwise OR of some set of -transformation flags. This call is equivalent to png_write_info(), -followed the set of transformations indicated by the transform mask, -then png_write_image(), and finally png_write_end(). - -(The final parameter of this call is not yet used. Someday it might point -to transformation parameters required by some future output transform.) - -You must use png_transforms and not call any png_set_transform() functions -when you use png_write_png(). - -The low-level write interface - -If you are going the low-level route instead, you are now ready to -write all the file information up to the actual image data. You do -this with a call to png_write_info(). - - png_write_info(png_ptr, info_ptr); - -Note that there is one transformation you may need to do before -png_write_info(). In PNG files, the alpha channel in an image is the -level of opacity. If your data is supplied as a level of transparency, -you can invert the alpha channel before you write it, so that 0 is -fully transparent and 255 (in 8-bit or paletted images) or 65535 -(in 16-bit images) is fully opaque, with - - png_set_invert_alpha(png_ptr); - -This must appear before png_write_info() instead of later with the -other transformations because in the case of paletted images the tRNS -chunk data has to be inverted before the tRNS chunk is written. If -your image is not a paletted image, the tRNS data (which in such cases -represents a single color to be rendered as transparent) won't need to -be changed, and you can safely do this transformation after your -png_write_info() call. - -If you need to write a private chunk that you want to appear before -the PLTE chunk when PLTE is present, you can write the PNG info in -two steps, and insert code to write your own chunk between them: - - png_write_info_before_PLTE(png_ptr, info_ptr); - png_set_unknown_chunks(png_ptr, info_ptr, ...); - png_write_info(png_ptr, info_ptr); - -After you've written the file information, you can set up the library -to handle any special transformations of the image data. The various -ways to transform the data will be described in the order that they -should occur. This is important, as some of these change the color -type and/or bit depth of the data, and some others only work on -certain color types and bit depths. Even though each transformation -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 or 6 bytes. This code tells -the library to strip input data that has 4 or 8 bytes per pixel down -to 3 or 6 bytes (or strip 2 or 4-byte grayscale+filler data to 1 or 2 -bytes per pixel). - - png_set_filler(png_ptr, 0, PNG_FILLER_BEFORE); - -where the 0 is unused, and the location is either PNG_FILLER_BEFORE or -PNG_FILLER_AFTER, depending upon whether the filler byte in the pixel -is stored XRGB or RGBX. - -PNG files pack pixels of bit depths 1, 2, and 4 into bytes as small as -they can, resulting in, for example, 8 pixels per byte for 1 bit files. -If the data is supplied at 1 pixel per byte, use this code, which will -correctly pack the pixels into a single byte: - - png_set_packing(png_ptr); - -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 recover the original data if desired. - - /* Set the true bit depth of the image data */ - if (color_type & PNG_COLOR_MASK_COLOR) - { - sig_bit.red = true_bit_depth; - sig_bit.green = true_bit_depth; - sig_bit.blue = true_bit_depth; - } - - else - { - sig_bit.gray = true_bit_depth; - } - - if (color_type & PNG_COLOR_MASK_ALPHA) - { - sig_bit.alpha = true_bit_depth; - } - - png_set_sBIT(png_ptr, info_ptr, &sig_bit); - -If the data is stored in the row buffer in a bit depth other than -one supported by PNG (e.g. 3 bit data in the range 0-7 for a 4-bit PNG), -this will scale the values to appear to be the correct bit depth as -is required by PNG. - - png_set_shift(png_ptr, &sig_bit); - -PNG files store 16-bit pixels in network byte order (big-endian, -ie. most significant bits first). This code would be used if they are -supplied the other way (little-endian, i.e. least significant bits -first, the way PCs store them): - - if (bit_depth > 8) - png_set_swap(png_ptr); - -If you are using packed-pixel images (1, 2, or 4 bits/pixel), and you -need to change the order the pixels are packed into bytes, you can use: - - if (bit_depth < 8) - png_set_packswap(png_ptr); - -PNG files store 3 color pixels in red, green, blue order. This code -would be used if they are supplied as blue, green, red: - - png_set_bgr(png_ptr); - -PNG files describe monochrome as black being zero and white being -one. This code would be used if the pixels are supplied with this reversed -(black being one and white being zero): - - png_set_invert_mono(png_ptr); - -Finally, you can write your own transformation function if none of -the existing ones meets your needs. This is done by setting a callback -with - - png_set_write_user_transform_fn(png_ptr, - write_transform_fn); - -You must supply the function - - void write_transform_fn(png_structp png_ptr, png_row_infop - row_info, png_bytep data) - -See pngtest.c for a working example. Your function will be called -before any of the other transformations are processed. If supported -libpng also supplies an information routine that may be called from -your callback: - - png_get_current_row_number(png_ptr); - png_get_current_pass_number(png_ptr); - -This returns the current row passed to the transform. With interlaced -images the value returned is the row in the input sub-image image. Use -PNG_ROW_FROM_PASS_ROW(row, pass) and PNG_COL_FROM_PASS_COL(col, pass) to -find the output pixel (x,y) given an interlaced sub-image pixel (row,col,pass). - -The discussion of interlace handling above contains more information on how to -use these values. - -You can also set up a pointer to a user structure for use by your -callback function. - - png_set_user_transform_info(png_ptr, user_ptr, 0, 0); - -The user_channels and user_depth parameters of this function are ignored -when writing; you can set them to zero as shown. - -You can retrieve the pointer via the function png_get_user_transform_ptr(). -For example: - - voidp write_user_transform_ptr = - png_get_user_transform_ptr(png_ptr); - -It is possible to have libpng flush any pending output, either manually, -or automatically after a certain number of lines have been written. To -flush the output stream a single time call: - - png_write_flush(png_ptr); - -and to have libpng flush the output stream periodically after a certain -number of scanlines have been written, call: - - png_set_flush(png_ptr, nrows); - -Note that the distance between rows is from the last time png_write_flush() -was called, or the first row of the image if it has never been called. -So if you write 50 lines, and then png_set_flush 25, it will flush the -output on the next scanline, and every 25 lines thereafter, unless -png_write_flush() is called before 25 more lines have been written. -If nrows is too small (less than about 10 lines for a 640 pixel wide -RGB image) the image compression may decrease noticeably (although this -may be acceptable for real-time applications). Infrequent flushing will -only degrade the compression performance by a few percent over images -that do not use flushing. - -Writing the image data - -That's it for the transformations. Now you can write the image data. -The simplest way to do this is in one function call. If you have the -whole image in memory, you can just call png_write_image() and libpng -will write the image. You will need to pass in an array of pointers to -each row. This function automatically handles interlacing, so you don't -need to call png_set_interlace_handling() or call this function multiple -times, or any of that other stuff necessary with png_write_rows(). - - png_write_image(png_ptr, row_pointers); - -where row_pointers is: - - png_byte *row_pointers[height]; - -You can point to void or char or whatever you use for pixels. - -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: - - png_write_rows(png_ptr, row_pointers, - number_of_rows); - -row_pointers is the same as in the png_write_image() call. - -If you are just writing one row at a time, you can do this with -a single row_pointer instead of an array of row_pointers: - - png_bytep row_pointer = row; - - png_write_row(png_ptr, row_pointer); - -When the file is interlaced, things can get a good deal more complicated. -The only currently (as of the PNG Specification version 1.2, dated July -1999) defined interlacing scheme for PNG files is the "Adam7" interlace -scheme, that breaks down an image into seven smaller images of varying -size. libpng will build these images for you, or you can do them -yourself. If you want to build them yourself, see the PNG specification -for details of which pixels to write when. - -If you don't want libpng to handle the interlacing details, just -use png_set_interlace_handling() and call png_write_rows() the -correct number of times to write all the sub-images -(png_set_interlace_handling() returns the number of sub-images.) - -If you want libpng to build the sub-images, call this before you start -writing any rows: - - number_of_passes = png_set_interlace_handling(png_ptr); - -This will return the number of passes needed. Currently, this is seven, -but may change if another interlace type is added. - -Then write the complete image number_of_passes times. - - png_write_rows(png_ptr, row_pointers, number_of_rows); - -Think carefully before you write an interlaced image. Typically code that -reads such images reads all the image data into memory, uncompressed, before -doing any processing. Only code that can display an image on the fly can -take advantage of the interlacing and even then the image has to be exactly -the correct size for the output device, because scaling an image requires -adjacent pixels and these are not available until all the passes have been -read. - -If you do write an interlaced image you will hardly ever need to handle -the interlacing yourself. Call png_set_interlace_handling() and use the -approach described above. - -The only time it is conceivable that you will really need to write an -interlaced image pass-by-pass is when you have read one pass by pass and -made some pixel-by-pixel transformation to it, as described in the read -code above. In this case use the PNG_PASS_ROWS and PNG_PASS_COLS macros -to determine the size of each sub-image in turn and simply write the rows -you obtained from the read code. - -Finishing a sequential write - -After you are finished writing the image, you should finish writing -the file. If you are interested in writing comments or time, you should -pass an appropriately filled png_info pointer. If you are not interested, -you can pass NULL. - - png_write_end(png_ptr, info_ptr); - -When you are done, you can free all memory used by libpng like this: - - png_destroy_write_struct(&png_ptr, &info_ptr); - -It is also possible to individually free the info_ptr members that -point to libpng-allocated storage with the following function: - - png_free_data(png_ptr, info_ptr, mask, seq) - - mask - identifies data to be freed, a mask - containing the bitwise OR of one or - more of - PNG_FREE_PLTE, PNG_FREE_TRNS, - PNG_FREE_HIST, PNG_FREE_ICCP, - PNG_FREE_PCAL, PNG_FREE_ROWS, - PNG_FREE_SCAL, PNG_FREE_SPLT, - PNG_FREE_TEXT, PNG_FREE_UNKN, - or simply PNG_FREE_ALL - - seq - sequence number of item to be freed - (-1 for all items) - -This function may be safely called when the relevant storage has -already been freed, or has not yet been allocated, or was allocated -by the user and not by libpng, and will in those cases do nothing. -The "seq" parameter is ignored if only one item of the selected data -type, such as PLTE, is allowed. If "seq" is not -1, and multiple items -are allowed for the data type identified in the mask, such as text or -sPLT, only the n'th item in the structure is freed, where n is "seq". - -If you allocated data such as a palette that you passed in to libpng -with png_set_*, you must not free it until just before the call to -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_calloc() and passed in via a png_set_*() function, with - - png_data_freer(png_ptr, info_ptr, freer, mask) - - freer - one of - PNG_DESTROY_WILL_FREE_DATA - PNG_SET_WILL_FREE_DATA - PNG_USER_WILL_FREE_DATA - - mask - which data elements are affected - same choices as in png_free_data() - -For example, to transfer responsibility for some data from a read structure -to a write structure, you could use - - png_data_freer(read_ptr, read_info_ptr, - PNG_USER_WILL_FREE_DATA, - PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) - - png_data_freer(write_ptr, write_info_ptr, - PNG_DESTROY_WILL_FREE_DATA, - PNG_FREE_PLTE|PNG_FREE_tRNS|PNG_FREE_hIST) - -thereby briefly reassigning responsibility for freeing to the user but -immediately afterwards reassigning it once more to the write_destroy -function. Having done this, it would then be safe to destroy the read -structure and continue to use the PLTE, tRNS, and hIST data in the write -structure. - -This function only affects data that has already been allocated. -You can call this function before calling after the png_set_*() functions -to control whether the user 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_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, -because when libpng fills a png_text structure it combines these members with -the key member, and png_free_data() will free only text_ptr.key. Similarly, -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. 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, set the - version field to PNG_IMAGE_VERSION and the 'opaque' pointer to NULL - (this is REQUIRED, your program may crash if you don't do it.) - - 2) Call the appropriate png_image_begin_read... function. - - 3) Set the png_image 'format' member to the required sample format. - - 4) Allocate a buffer for the image and, if required, the color-map. - - 5) Call png_image_finish_read to read the image and, if required, the - color-map into your buffers. - -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. The only caveat is that if you -request a color-mapped image from a PNG that is full-color or makes -complex use of an alpha channel the transformation is extremely lossy and the -result may look terrible. - -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 samples. - - 3) Call the appropriate png_image_write... function with a - pointer to the image and, if necessary, the color-map 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 defines the in-memory format of an image that you -need to write. The "png_image" structure contains the following members: - - png_controlp opaque Initialize to NULL, free with png_image_free - 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_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 "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 the "warning_or_error" 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 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 https://en.wikipedia.org/wiki/SRGB) is used, not the gamma=1/2.2 -approximation used elsewhere in libpng. - -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. - -The samples are either contained directly in the image data, between 1 and 8 -bytes per pixel according to the encoding, or are held in a color-map indexed -by bytes in the image data. In the case of a color-map the color-map entries -are individual samples, encoded as above, and the image data has one byte per -pixel to select the relevant sample from the color-map. - -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 component encodings. - -A format is built up using single bit flag values. All combinations are -valid. Formats can be built up from the flag values or you can use one of -the predefined values below. When testing formats always use the FORMAT_FLAG -macros to test for individual features - future versions of the library may -add new flags. - -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 the -appropriate "_SUPPORTED" macro, one of: - - PNG_SIMPLIFIED_{READ,WRITE}_{BGR,AFIRST}_SUPPORTED - - PNG_FORMAT_FLAG_ALPHA format with an alpha channel - PNG_FORMAT_FLAG_COLOR color format: otherwise grayscale - PNG_FORMAT_FLAG_LINEAR 2-byte channels else 1-byte - PNG_FORMAT_FLAG_COLORMAP image data is color-mapped - PNG_FORMAT_FLAG_BGR BGR colors, else order is RGB - PNG_FORMAT_FLAG_AFIRST 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 (sRGB) formats: - - PNG_FORMAT_GRAY - PNG_FORMAT_GA - PNG_FORMAT_AG - PNG_FORMAT_RGB - PNG_FORMAT_BGR - PNG_FORMAT_RGBA - PNG_FORMAT_ARGB - PNG_FORMAT_BGRA - PNG_FORMAT_ABGR - -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_LINEAR_Y_ALPHA - PNG_FORMAT_LINEAR_RGB - PNG_FORMAT_LINEAR_RGB_ALPHA - -With color-mapped formats the image data is one byte for each pixel. The byte -is an index into the color-map which is formatted as above. To obtain a -color-mapped format it is sufficient just to add the PNG_FOMAT_FLAG_COLORMAP -to one of the above definitions, or you can use one of the definitions below. - - PNG_FORMAT_RGB_COLORMAP - PNG_FORMAT_BGR_COLORMAP - PNG_FORMAT_RGBA_COLORMAP - PNG_FORMAT_ARGB_COLORMAP - PNG_FORMAT_BGRA_COLORMAP - PNG_FORMAT_ABGR_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 for color-mapped formats. 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. - - 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: 1 or 2. - - 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_MAXIMUM_COLORMAP_COMPONENTS(fmt) - 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. - - 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. - -Corresponding information about the pixels - - 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) - Return 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. - - PNG_IMAGE_SIZE(image) - Return the size, in bytes, of the image in memory given just a png_image; - the row stride is the minimum stride required for the image. - - PNG_IMAGE_COLORMAP_SIZE(image) - Return the size, in bytes, of the color-map of this image. If the image - format is not a color-map format this will return a size sufficient for - 256 entries in the given format; check PNG_FORMAT_FLAG_COLORMAP if - you don't want to allocate a color-map in this case. - -PNG_IMAGE_FLAG_* - -Flags containing additional information about the image are held in -the 'flags' field of png_image. - - 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_FAST == 0x02 - On write emphasise speed over compression; the resultant PNG file will be - larger but will be produced significantly faster, particular for large - images. Do not use this option for images which will be distributed, only - used it when producing intermediate files that will be read back in - repeatedly. For a typical 24-bit image the option will double the read - speed at the cost of increasing the image size by 25%, however for many - more compressible images the PNG file can be 10 times larger with only a - slight speed gain. - - PNG_IMAGE_FLAG_16BIT_sRGB == 0x04 - On read if the image is a 16-bit per component image and there is no gAMA - or sRGB chunk assume that the components are sRGB encoded. Notice that - images output by the simplified API always have gamma information; setting - this flag only affects the interpretation of 16-bit images from an - external source. It is recommended that the application expose this flag - to the user; the user can normally easily recognize the difference between - linear and sRGB encoding. This flag has no effect on write - the data - passed to the write APIs must have the correct encoding (as defined - above.) - - If the flag is not set (the default) input 16-bit per component data is - assumed to be linear. - - NOTE: the flag can only be set after the png_image_begin_read_ call, - because that call initializes the 'flags' field. - -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 https://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_memory (png_imagep image, void *memory, - png_alloc_size_t * PNG_RESTRICT memory_bytes, - int convert_to_8_bit, const void *buffer, ptrdiff_t row_stride, - const void *colormap)); - - Write the image to memory. - - 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. If you pass zero, libpng will -calculate the row_stride for you from the width and number of channels. - -Note that the write API does not support interlacing, sub-8-bit pixels, -indexed (paletted) images, or most ancillary chunks. - -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. -The second deals with more complicated things like adding new chunks, -adding new transformations, and generally changing how libpng works. -Both of those are compile-time issues; that is, they are generally -determined at the time the code is written, and there is rarely a need -to provide the user with a means of changing them. - -Memory allocation, input/output, and error handling - -All of the memory allocation, input/output, and error handling in libpng -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. - -Memory allocation is done through the functions png_malloc(), png_calloc(), -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); - -Your replacement memory functions must have prototypes as follows: - - png_voidp malloc_fn(png_structp png_ptr, - png_alloc_size_t size); - - void free_fn(png_structp png_ptr, png_voidp ptr); - -Your malloc_fn() must return NULL in case of failure. The png_malloc() -function will normally call png_error() if it receives a NULL from the -system memory allocator or from your replacement malloc_fn(). - -Your free_fn() will never be called with a NULL ptr, since libpng's -png_free() checks for NULL before calling free_fn(). - -Input/Output in libpng is done through png_read() and png_write(), -which currently just call fread() and fwrite(). The FILE * is stored in -png_struct and is initialized via png_init_io(). If you wish to change -the method of I/O, the library supplies callbacks that you can set -through the function png_set_read_fn() and png_set_write_fn() at run -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 read_ptr, - voidp read_io_ptr, png_rw_ptr read_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 read_io_ptr = png_get_io_ptr(read_ptr); - voidp write_io_ptr = png_get_io_ptr(write_ptr); - -The replacement I/O functions must have prototypes as follows: - - void user_read_data(png_structp png_ptr, - png_bytep data, png_size_t length); - - void user_write_data(png_structp png_ptr, - png_bytep data, png_size_t length); - - void user_flush_data(png_structp png_ptr); - -The user_read_data() function is responsible for detecting and -handling end-of-data errors. - -Supplying NULL for the read, write, or flush functions sets them back -to using the default C stream functions, which expect the io_ptr to -point to a standard *FILE structure. It is probably a mistake -to use NULL for one of write_data_fn and output_flush_fn but not both -of them, unless you have built libpng with PNG_NO_WRITE_FLUSH defined. -It is an error to read from a write stream, and vice versa. - -Error handling in libpng is done through png_error() and png_warning(). -Errors handled through png_error() are fatal, meaning that png_error() -should never return to its caller. Currently, this is handled via -setjmp() and longjmp() (unless you have compiled libpng with -PNG_NO_SETJMP, in which case it is handled via PNG_ABORT()), -but you could change this to do things like exit() if you should wish, -as long as your function does not return. - -On non-fatal errors, png_warning() is called -to print a warning message, and then control returns to the calling code. -By default png_error() and png_warning() print a message on stderr via -fprintf() unless the library is compiled with PNG_NO_CONSOLE_IO defined -(because you don't want the messages) or PNG_NO_STDIO defined (because -fprintf() isn't available). If you wish to change the behavior of the error -functions, you will need to set up your own message callbacks. These -functions are normally supplied at the time that the png_struct is created. -It is also possible to redirect errors and warnings to your own replacement -functions after png_create_*_struct() has been called by calling: - - png_set_error_fn(png_structp png_ptr, - png_voidp error_ptr, png_error_ptr error_fn, - png_error_ptr warning_fn); - -If NULL is supplied for either error_fn or warning_fn, then the libpng -default function will be used, calling fprintf() and/or longjmp() if a -problem is encountered. The replacement error functions should have -parameters as follows: - - void user_error_fn(png_structp png_ptr, - png_const_charp error_msg); - - void user_warning_fn(png_structp png_ptr, - png_const_charp warning_msg); - -Then, within your user_error_fn or user_warning_fn, you can retrieve -the error_ptr if you need it, by calling - - png_voidp error_ptr = png_get_error_ptr(png_ptr); - -The motivation behind using setjmp() and longjmp() is the C++ throw and -catch exception handling methods. This makes the code much easier to write, -as there is no need to check every return code of every function call. -However, there are some uncertainties about the status of local variables -after a longjmp, so the user may want to be careful about doing anything -after setjmp returns non-zero besides returning itself. Consult your -compiler documentation for more details. For an alternative approach, you -may wish to use the "cexcept" facility (see https://cexcept.sourceforge.io/), -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 -into the libpng code. The library now has mechanisms for storing -and writing chunks of unknown type; you can even declare callbacks -for custom chunks. However, this may not be good enough if the -library code itself needs to know about interactions between your -chunk and existing `intrinsic' chunks. - -If you need to write a new intrinsic chunk, first read the PNG -specification. Acquire a first level of understanding of how it works. -Pay particular attention to the sections that describe chunk names, -and look at how other chunks were designed, so you can do things -similarly. Second, check out the sections of libpng that read and -write chunks. Try to find a chunk that is similar to yours and use -it as a template. More details can be found in the comments inside -the code. It is best to handle private or unknown chunks in a generic method, -via callback functions, instead of by modifying libpng functions. This -is illustrated in pngtest.c, which uses a callback function to handle a -private "vpAg" chunk and the new "sTER" chunk, which are both unknown to -libpng. - -If you wish to write your own transformation for the data, look through -the part of the code that does the transformations, and check out some of -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 gui/windowing platforms: - -You will need to write new error and warning functions that use the GUI -interface, as described previously, and set them to be the error and -warning functions at the time that png_create_*_struct() is called, -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 zlib: - -There are special functions to configure the compression. Perhaps the -most useful one changes the compression level, which currently uses -input compression values in the range 0 - 9. The library normally -uses the default compression level (Z_DEFAULT_COMPRESSION = 6). Tests -have shown that for a large majority of images, compression values in -the range 3-6 compress nearly as well as higher levels, and do so much -faster. For online applications it may be desirable to have maximum speed -(Z_BEST_SPEED = 1). With versions of zlib after v0.99, you can also -specify no compression (Z_NO_COMPRESSION = 0), but this would create -files larger than just storing the raw bitmap. You can specify the -compression level by calling: - - #include zlib.h - png_set_compression_level(png_ptr, level); - -Another useful one is to reduce the memory level used by the library. -The memory level defaults to 8, but it can be lowered if you are -short on memory (running DOS, for example, where you only have 640K). -Note that the memory level does have an effect on compression; among -other things, lower levels will result in sections of incompressible -data being emitted in smaller stored blocks, with a correspondingly -larger relative overhead of up to 15% in the worst case. - - #include zlib.h - png_set_compression_mem_level(png_ptr, level); - -The other functions are for configuring zlib. They are not recommended -for normal use and may result in writing an invalid PNG file. See -zlib.h for more information on what these mean. - - #include zlib.h - png_set_compression_strategy(png_ptr, - strategy); - - png_set_compression_window_bits(png_ptr, - window_bits); - - 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 -available to set these separately for non-IDAT -compressed chunks such as zTXt, iTXt, and iCCP: - - #include zlib.h - #if PNG_LIBPNG_VER >= 10504 - png_set_text_compression_level(png_ptr, level); - - png_set_text_compression_mem_level(png_ptr, level); - - png_set_text_compression_strategy(png_ptr, - strategy); - - png_set_text_compression_window_bits(png_ptr, - window_bits); - - png_set_text_compression_method(png_ptr, method); - #endif - -Controlling row filtering - -If you want to control whether libpng uses filtering or not, which -filters are used, and how it goes about picking row filters, you -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), 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.2 specification. The 'filters' -parameter sets which filter(s), if any, should be used for each -scanline. Possible values are PNG_ALL_FILTERS, PNG_NO_FILTERS, -or PNG_FAST_FILTERS to turn filtering on and off, or to turn on -just the fast-decoding subset of filters, respectively. - -Individual filter types are PNG_FILTER_NONE, PNG_FILTER_SUB, -PNG_FILTER_UP, PNG_FILTER_AVG, PNG_FILTER_PAETH, which can be bitwise -ORed together with '|' to specify one or more filters to use. -These filters are described in more detail in the PNG specification. -If you intend to change the filter type during the course of writing -the image, you should start with flags set for all of the filters -you intend to use so that libpng can initialize its internal -structures appropriately for all of the filter types. (Note that this -means the first row must always be adaptively filtered, because libpng -currently does not allocate the filter buffers until png_write_row() -is called for the first time.) - - filters = PNG_NO_FILTERS; - filters = PNG_ALL_FILTERS; - filters = PNG_FAST_FILTERS; - - or - - filters = PNG_FILTER_NONE | PNG_FILTER_SUB | - PNG_FILTER_UP | PNG_FILTER_AVG | - PNG_FILTER_PAETH; - - png_set_filter(png_ptr, PNG_FILTER_TYPE_BASE, - filters); - - The second parameter can also be - PNG_INTRAPIXEL_DIFFERENCING if you are - writing a PNG to be embedded in a MNG - datastream. This parameter must be the - same as the value of filter_method used - in png_set_IHDR(). - -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", foo); - -is expanded to - - 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. - -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. -Libpng can support some of these extensions. To enable them, use the -png_permit_mng_features() function: - - feature_set = png_permit_mng_features(png_ptr, mask) - - mask is a png_uint_32 containing the bitwise OR of the - features you want to enable. These include - PNG_FLAG_MNG_EMPTY_PLTE - PNG_FLAG_MNG_FILTER_64 - PNG_ALL_MNG_FEATURES - - feature_set is a png_uint_32 that is the bitwise AND of - your mask with the set of MNG features that is - supported by the version of libpng that you are using. - -It is an error to use this function when reading or writing a standalone -PNG file with the PNG 8-byte signature. The PNG datastream must be wrapped -in a MNG datastream. As a minimum, it must have the MNG 8-byte signature -and the MHDR and MEND chunks. Libpng does not provide support for these -or any other MNG chunks; your application must provide its own support for -them. You may wish to consider using libmng (available at -https://www.libmng.com/) instead. - -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 -Andreas Dilger, who had taken over from Guy during 1996 and 1997, and -distributed versions 0.89 through 0.96, but rather by another member -of the original PNG Group, Glenn Randers-Pehrson. Guy and Andreas are -still alive and well, but they have moved on to other things. - -The old libpng functions png_read_init(), png_write_init(), -png_info_init(), png_read_destroy(), and png_write_destroy() have been -moved to PNG_INTERNAL in version 0.95 to discourage their use. These -functions will be removed from libpng version 1.4.0. - -The preferred method of creating and initializing the libpng structures is -via the png_create_read_struct(), png_create_write_struct(), and -png_create_info_struct() because they isolate the size of the structures -from the application, allow version error checking, and also allow the -use of custom error handling routines during the initialization, which -the old functions do not. The functions png_read_destroy() and -png_write_destroy() do not actually free the memory that libpng -allocated for these structs, but just reset the data structures, so they -can be used instead of png_destroy_read_struct() and -png_destroy_write_struct() if you feel there is too much system overhead -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 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. - -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: - - png_uint_32 libpng_vn = png_access_version_number(); - -The number libpng_vn is constructed from the major version, minor -version with leading zero, and release number with leading zero, -(e.g., libpng_vn for version 1.0.7 is 10007). - -Note that this function does not take a png_ptr, so you can call it -before you've created one. - -You can also check which version of png.h you used when compiling your -application: - - png_uint_32 application_vn = PNG_LIBPNG_VER; - -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(), -png_create_write_struct_2(), png_set_mem_fn(), png_get_mem_ptr(), -png_malloc_default(), and png_free_default() were added. - -Support for the iTXt chunk has been enabled by default as of -version 1.2.41. - -Support for certain MNG features was enabled. - -Support for numbered error messages was added. However, we never got -around to actually numbering the error messages. The function -png_set_strip_error_numbers() was added (Note: the prototype for this -function was inadvertently removed from png.h in PNG_NO_ASSEMBLER_CODE -builds of libpng-1.2.15. It was restored in libpng-1.2.36). - -The png_malloc_warn() function was added at libpng-1.2.3. This issues -a png_warning and returns NULL instead of aborting when it fails to -acquire the requested memory allocation. - -Support for setting user limits on image width and height was enabled -by default. The functions png_set_user_limits(), png_get_user_width_max(), -and png_get_user_height_max() were added at libpng-1.2.6. - -The png_set_add_alpha() function was added at libpng-1.2.7. - -The function png_set_expand_gray_1_2_4_to_8() was added at libpng-1.2.9. -Unlike png_set_gray_1_2_4_to_8(), the new function does not expand the -tRNS chunk to alpha. The png_set_gray_1_2_4_to_8() function is -deprecated. - -A number of macro definitions in support of runtime selection of -assembler code features (especially Intel MMX code support) were -added at libpng-1.2.0: - - PNG_ASM_FLAG_MMX_SUPPORT_COMPILED - PNG_ASM_FLAG_MMX_SUPPORT_IN_CPU - PNG_ASM_FLAG_MMX_READ_COMBINE_ROW - PNG_ASM_FLAG_MMX_READ_INTERLACE - PNG_ASM_FLAG_MMX_READ_FILTER_SUB - PNG_ASM_FLAG_MMX_READ_FILTER_UP - PNG_ASM_FLAG_MMX_READ_FILTER_AVG - PNG_ASM_FLAG_MMX_READ_FILTER_PAETH - PNG_ASM_FLAGS_INITIALIZED - PNG_MMX_READ_FLAGS - PNG_MMX_FLAGS - PNG_MMX_WRITE_FLAGS - PNG_MMX_FLAGS - -We added the following functions in support of runtime -selection of assembler code features: - - png_get_mmx_flagmask() - png_set_mmx_thresholds() - png_get_asm_flags() - png_get_mmx_bitdepth_threshold() - png_get_mmx_rowbytes_threshold() - png_set_asm_flags() - -We replaced all of these functions with simple stubs in libpng-1.2.20, -when the Intel assembler code was removed due to a licensing issue. - -These macros are deprecated: - - PNG_READ_TRANSFORMS_NOT_SUPPORTED - PNG_PROGRESSIVE_READ_NOT_SUPPORTED - PNG_NO_SEQUENTIAL_READ_SUPPORTED - PNG_WRITE_TRANSFORMS_NOT_SUPPORTED - PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED - PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED - -They have been replaced, respectively, by: - - PNG_NO_READ_TRANSFORMS - PNG_NO_PROGRESSIVE_READ - PNG_NO_SEQUENTIAL_READ - PNG_NO_WRITE_TRANSFORMS - PNG_NO_READ_ANCILLARY_CHUNKS - PNG_NO_WRITE_ANCILLARY_CHUNKS - -PNG_MAX_UINT was replaced with PNG_UINT_31_MAX. It has been -deprecated since libpng-1.0.16 and libpng-1.2.6. - -The function - png_check_sig(sig, num) -was replaced with - !png_sig_cmp(sig, 0, num) -It has been deprecated since libpng-0.90. - -The function - png_set_gray_1_2_4_to_8() -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. - -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. - -Functions png_set_benign_errors(), png_benign_error(), and -png_chunk_benign_error() were added. - -Support for setting the maximum amount of memory that the application -will allocate for reading chunks was added, as a security measure. -The functions png_set_chunk_cache_max() and png_get_chunk_cache_max() -were added to the library. - -We implemented support for I/O states by adding png_ptr member io_state -and functions png_get_io_chunk_name() and png_get_io_state() in pngget.c - -We added PNG_TRANSFORM_GRAY_TO_RGB to the available high-level -input transforms. - -Checking for and reporting of errors in the IHDR chunk is more thorough. - -Support for global arrays was removed, to improve thread safety. - -Some obsolete/deprecated macros and functions have been removed. - -Typecasted NULL definitions such as - #define png_voidp_NULL (png_voidp)NULL -were eliminated. If you used these in your application, just use -NULL instead. - -The png_struct and info_struct members "trans" and "trans_values" were -changed to "trans_alpha" and "trans_color", respectively. - -The obsolete, unused pnggccrd.c and pngvcrd.c files and related makefiles -were removed. - -The PNG_1_0_X and PNG_1_2_X macros were eliminated. - -The PNG_LEGACY_SUPPORTED macro was eliminated. - -Many WIN32_WCE #ifdefs were removed. - -The functions png_read_init(info_ptr), png_write_init(info_ptr), -png_info_init(info_ptr), png_read_destroy(), and png_write_destroy() -have been removed. They have been deprecated since libpng-0.95. - -The png_permit_empty_plte() was removed. It has been deprecated -since libpng-1.0.9. Use png_permit_mng_features() instead. - -We removed the obsolete stub functions png_get_mmx_flagmask(), -png_set_mmx_thresholds(), png_get_asm_flags(), -png_get_mmx_bitdepth_threshold(), png_get_mmx_rowbytes_threshold(), -png_set_asm_flags(), and png_mmx_supported() - -We removed the obsolete png_check_sig(), png_memcpy_check(), and -png_memset_check() functions. Instead use !png_sig_cmp(), memcpy(), -and memset(), respectively. - -The function png_set_gray_1_2_4_to_8() was removed. It has been -deprecated since libpng-1.0.18 and 1.2.9, when it was replaced with -png_set_expand_gray_1_2_4_to_8() because the former function also -expanded any tRNS chunk to an alpha channel. - -Macros for png_get_uint_16, png_get_uint_32, and png_get_int_32 -were added and are used by default instead of the corresponding -functions. Unfortunately, -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. - -We changed the prototype for png_malloc() from - png_malloc(png_structp png_ptr, png_uint_32 size) -to - png_malloc(png_structp png_ptr, png_alloc_size_t size) - -This also applies to the prototype for the user replacement malloc_fn(). - -The png_calloc() function was added and is used in place of -of "png_malloc(); memset();" except in the case in png_read_png() -where the array consists of pointers; in this case a "for" loop is used -after the png_malloc() to set the pointers to NULL, to give robust. -behavior in case the application runs out of memory part-way through -the process. - -We changed the prototypes of png_get_compression_buffer_size() and -png_set_compression_buffer_size() to work with png_size_t instead of -png_uint_32. - -Support for numbered error messages was removed by default, since we -never got around to actually numbering the error messages. The function -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. 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 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 -was renamed to PNG_READ_QUANTIZE_SUPPORTED. - -We removed the trailing '.' from the warning and error messages. - -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 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 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); - -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 -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, and new private "pngstruct.h", "pnginfo.h", and "pngdebug.h" -header files were created. - -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. - -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. - -There are changes of form in png.h, including new and changed macros to -declare parts of the API. Some API functions with arguments that are -pointers to data not modified within the function have been corrected to -declare these arguments with PNG_CONST. - -Much of the internal use of C macros to control the library build has also -changed and some of this is visible in the exported header files, in -particular the use of macros to control data and API elements visible -during application compilation may require significant revision to -application code. (It is extremely rare for an application to do this.) - -Any program that compiled against libpng 1.4 and did not use deprecated -features or access internal library structures should compile and work -against libpng 1.5, except for the change in the prototype for -png_get_iCCP() and png_set_iCCP() API functions mentioned above. - -libpng 1.5.0 adds PNG_ PASS macros to help in the reading and writing of -interlaced images. The macros return the number of rows and columns in -each pass and information that can be used to de-interlace and (if -absolutely necessary) interlace an image. - -libpng 1.5.0 adds an API png_longjmp(png_ptr, value). This API calls -the application-provided png_longjmp_ptr on the internal, but application -initialized, longjmp buffer. It is provided as a convenience to avoid -the need to use the png_jmpbuf macro, which had the unnecessary side -effect of resetting the internal png_longjmp_ptr value. - -libpng 1.5.0 includes a complete fixed point API. By default this is -present along with the corresponding floating point API. In general the -fixed point API is faster and smaller than the floating point one because -the PNG file format used fixed point, not floating point. This applies -even if the library uses floating point in internal calculations. A new -macro, PNG_FLOATING_ARITHMETIC_SUPPORTED, reveals whether the library -uses floating point arithmetic (the default) or fixed point arithmetic -internally for performance critical calculations such as gamma correction. -In some cases, the gamma calculations may produce slightly different -results. This has changed the results in png_rgb_to_gray and in alpha -composition (png_set_background for example). This applies even if the -original image was already linear (gamma == 1.0) and, therefore, it is -not necessary to linearize the image. This is because libpng has *not* -been changed to optimize that case correctly, yet. - -Fixed point support for the sCAL chunk comes with an important caveat; -the sCAL specification uses a decimal encoding of floating point values -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. 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 -build in order to see the correct variant of the libpng API. From 1.5.0 -application code can check for the corresponding _SUPPORTED macro: - -#ifdef PNG_INCH_CONVERSIONS_SUPPORTED - /* code that uses the inch conversion APIs. */ -#endif - -This macro will only be defined if the inch conversion functions have been -compiled into libpng. The full set of macros, and whether or not support -has been compiled in, are available in the header file pnglibconf.h. -This header file is specific to the libpng build. Notice that prior to -1.5.0 the _SUPPORTED macros would always have the default definition unless -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. - -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 -will lead to a link failure. - -Prior to libpng-1.5.4, the zlib compressor used the same set of parameters -when compressing the IDAT data and textual data such as zTXt and iCCP. -In libpng-1.5.4 we reinitialized the zlib stream for each type of data. -We added five png_set_text_*() functions for setting the parameters to -use with textual data. - -Prior to libpng-1.5.4, the PNG_READ_16_TO_8_ACCURATE_SCALE_SUPPORTED -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. 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 -PNG_USER_WIDTH_MAX and PNG_USER_HEIGHT_MAX, although this document said -that it could be used to override them. Now this function will reduce or -increase the limits. - -Starting in libpng-1.5.22, default user limits were established. These -can be overridden by application calls to png_set_user_limits(), -png_set_user_chunk_cache_max(), and/or png_set_user_malloc_max(). -The limits are now - max possible default - png_user_width_max 0x7fffffff 1,000,000 - png_user_height_max 0x7fffffff 1,000,000 - png_user_chunk_cache_max 0 (unlimited) 1000 - png_user_chunk_malloc_max 0 (unlimited) 8,000,000 - -The png_set_option() function (and the "options" member of the png struct) was -added to libpng-1.5.15, with option PNG_ARM_NEON. - -The library now supports a complete fixed point implementation and can -thus be used on systems that have no floating point support or very -limited or slow support. Previously gamma correction, an essential part -of complete PNG support, required reasonably fast floating point. - -As part of this the choice of internal implementation has been made -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, 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 -calculations and includes a number of validations of the file format. -A subset of the full range of tests is run when "make check" is done -(in the 'configure' build.) pngvalid also allows total allocated memory -usage to be evaluated and performs additional memory overwrite validation. - -Many changes to individual feature macros have been made. The following -are the changes most likely to be noticed by library builders who -configure libpng: - -1) All feature macros now have consistent naming: - -#define PNG_NO_feature turns the feature off -#define PNG_feature_SUPPORTED turns the feature on - -pnglibconf.h contains one line for each feature macro which is either: - -#define PNG_feature_SUPPORTED - -if the feature is supported or: - -/*#undef PNG_feature_SUPPORTED*/ - -if it is not. Library code consistently checks for the 'SUPPORTED' macro. -It does not, and libpng applications should not, check for the 'NO' macro -which will not normally be defined even if the feature is not supported. -The 'NO' macros are only used internally for setting or not setting the -corresponding 'SUPPORTED' macros. - -Compatibility with the old names is provided as follows: - -PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED - -And the following definitions disable the corresponding feature: - -PNG_SETJMP_NOT_SUPPORTED disables SETJMP -PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS -PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV -PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS -PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS -PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS - -Library builders should remove use of the above, inconsistent, names. - -2) Warning and error message formatting was previously conditional on -the STDIO feature. The library has been changed to use the -CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled -the library no longer uses the printf(3) functions, even though the -default read/write implementations use (FILE) style stdio.h functions. - -3) Three feature macros now control the fixed/floating point decisions: - -PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs - -PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in -practice these are normally required internally anyway (because the PNG -file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT -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 -system which lacks floating point hardware and therefore uses a software -emulation. - -4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED. This allows the -functions to read and write ints to be disabled independently of -PNG_USE_READ_MACROS, which allows libpng to be built with the functions -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.) - -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_memory() - 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 ' -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". - -Dropped support for 16-bit platforms. 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. - -Libpng 1.5.x erroneously used /MD for Debug DLL builds; if you used the debug -builds in your app and you changed your app to use /MD you will need to -change it back to /MDd for libpng 1.6.x. - -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. - -Starting with libpng-1.6.17, the PNG_SAFE_LIMITS macro was eliminated -and safe limits are used by default (users who need larger limits -can still override them at compile time or run time, as described above). - -The new limits are - default spec limit - png_user_width_max 1,000,000 2,147,483,647 - png_user_height_max 1,000,000 2,147,483,647 - png_user_chunk_cache_max 128 unlimited - png_user_chunk_malloc_max 8,000,000 unlimited - -Starting with libpng-1.6.18, a PNG_RELEASE_BUILD macro was added, which allows -library builders to control compilation for an installed system (a release build). -It can be set for testing debug or beta builds to ensure that they will compile -when the build type is switched to RC or STABLE. In essence this overrides the -PNG_LIBPNG_BUILD_BASE_TYPE definition which is not directly user controllable. - -Starting with libpng-1.6.19, attempting to set an over-length PLTE chunk -is an error. Previously this requirement of the PNG specification was not -enforced, and the palette was always limited to 256 entries. An over-length -PLTE chunk found in an input PNG is silently truncated. - -Starting with libpng-1.6.31, the eXIf chunk is supported. Libpng does not -attempt to decode the Exif profile; it simply returns a byte array -containing the profile to the calling application which must do its own -decoding. - -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 -best choice for use in configure scripts for detecting the presence of any -libpng version since 0.88. In an autoconf "configure.in" you could use - - AC_CHECK_LIB(png, png_get_io_ptr, ... - -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 - - https://github.com/glennrp/libpng or - https://git.code.sf.net/p/libpng/code.git - -or you can browse it with a web browser at - - https://github.com/glennrp/libpng or - https://sourceforge.net/p/libpng/code/ci/libpng16/tree/ - -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 -the libpng bug tracker at - - https://libpng.sourceforge.io/ - -or as a "pull request" to - - https://github.com/glennrp/libpng/pulls - -We also accept patches built from the tar or zip distributions, and -simple verbal discriptions of bug fixes, reported either to the -SourceForge bug tracker, to the png-mng-implement at lists.sf.net -mailing list, as github issues, or directly to glennrp. - -XV. Coding style - -Our coding style is similar to the "Allman" style -(See https://en.wikipedia.org/wiki/Indent_style#Allman_style), with curly -braces on separate lines: - - if (condition) - { - action; - } - - else if (another condition) - { - another action; - } - -The braces can be omitted from simple one-line actions: - - if (condition) - return (0); - -We use 3-space indentation, except for continued statements which -are usually indented the same as the first line of the statement -plus four more spaces. - -For macro definitions we use 2-space indentation, always leaving the "#" -in the first column. - - #ifndef PNG_NO_FEATURE - # ifndef PNG_FEATURE_SUPPORTED - # define PNG_FEATURE_SUPPORTED - # endif - #endif - -Comments appear with the leading "/*" at the same indentation as -the statement that follows the comment: - - /* Single-line comment */ - statement; - - /* This is a multiple-line - * comment. - */ - statement; - -Very short comments can be placed after the end of the statement -to which they pertain: - - statement; /* comment */ - -We don't use C++ style ("//") comments. We have, however, -used them in the past in some now-abandoned MMX assembler -code. - -Functions and their curly braces are not indented, and -exported functions are marked with PNGAPI: - - /* This is a public function that is visible to - * application programmers. It does thus-and-so. - */ - void PNGAPI - png_exported_function(png_ptr, png_info, foo) - { - 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 - - /* Maintainer: Put new public prototypes here ... */ - -We mark all non-exported functions with "/* PRIVATE */"": - - void /* PRIVATE */ - png_non_exported_function(png_ptr, png_info, foo) - { - body; - } - -The prototypes for non-exported functions (except for those in -pngtest) appear in pngpriv.h above the comment that says - - /* 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 -"?". We don't put a space between a typecast and the expression -being cast, nor do we put one between a function name and the -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 always use parentheses -with "defined". - -We express integer constants that are used as bit masks in hex format, -with an even number of lower-case hex digits, and to make them unsigned -(e.g., 0x00U, 0xffU, 0x0100U) and long if they are greater than 0x7fff -(e.g., 0xffffUL). - -We prefer to use underscores rather than camelCase in names, 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, and for pointers -we prefer "if (some_pointer != NULL)" or "if (some_pointer == NULL)". - -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. - -XVI. Y2K Compliance in libpng - -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.6.34 are Y2K compliant. It is my belief that earlier -versions were also Y2K compliant. - -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 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_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 - 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 that they are 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. - -zlib, upon which libpng depends, is also Y2K compliant. It contains -no date-related code. - - - Glenn Randers-Pehrson - libpng maintainer - PNG Development Group diff --git a/libs/liblua/docs/contents.html b/libs/liblua/docs/contents.html deleted file mode 100644 index c4eb267790..0000000000 --- a/libs/liblua/docs/contents.html +++ /dev/null @@ -1,619 +0,0 @@ - - - -Lua 5.3 Reference Manual - contents - - - - - - - -

-Lua -Lua 5.3 Reference Manual -

- -

-The reference manual is the official definition of the Lua language. -
-For a complete introduction to Lua programming, see the book -Programming in Lua. - -

-start -· -contents -· -index -· -other versions -
- -

- -Copyright © 2015–2018 Lua.org, PUC-Rio. -Freely available under the terms of the -Lua license. - - -

Contents

- - -

Index

- - - - - - - -
-

Lua functions

-

-basic
-_G
-_VERSION
-assert
-collectgarbage
-dofile
-error
-getmetatable
-ipairs
-load
-loadfile
-next
-pairs
-pcall
-print
-rawequal
-rawget
-rawlen
-rawset
-require
-select
-setmetatable
-tonumber
-tostring
-type
-xpcall
- -

-coroutine
-coroutine.create
-coroutine.isyieldable
-coroutine.resume
-coroutine.running
-coroutine.status
-coroutine.wrap
-coroutine.yield
- -

-debug
-debug.debug
-debug.gethook
-debug.getinfo
-debug.getlocal
-debug.getmetatable
-debug.getregistry
-debug.getupvalue
-debug.getuservalue
-debug.sethook
-debug.setlocal
-debug.setmetatable
-debug.setupvalue
-debug.setuservalue
-debug.traceback
-debug.upvalueid
-debug.upvaluejoin
- -

-io
-io.close
-io.flush
-io.input
-io.lines
-io.open
-io.output
-io.popen
-io.read
-io.stderr
-io.stdin
-io.stdout
-io.tmpfile
-io.type
-io.write
- -file:close
-file:flush
-file:lines
-file:read
-file:seek
-file:setvbuf
-file:write
- -

 -

 

-

-math
-math.abs
-math.acos
-math.asin
-math.atan
-math.ceil
-math.cos
-math.deg
-math.exp
-math.floor
-math.fmod
-math.huge
-math.log
-math.max
-math.maxinteger
-math.min
-math.mininteger
-math.modf
-math.pi
-math.rad
-math.random
-math.randomseed
-math.sin
-math.sqrt
-math.tan
-math.tointeger
-math.type
-math.ult
- -

-os
-os.clock
-os.date
-os.difftime
-os.execute
-os.exit
-os.getenv
-os.remove
-os.rename
-os.setlocale
-os.time
-os.tmpname
- -

-package
-package.config
-package.cpath
-package.loaded
-package.loadlib
-package.path
-package.preload
-package.searchers
-package.searchpath
- -

-string
-string.byte
-string.char
-string.dump
-string.find
-string.format
-string.gmatch
-string.gsub
-string.len
-string.lower
-string.match
-string.pack
-string.packsize
-string.rep
-string.reverse
-string.sub
-string.unpack
-string.upper
- -

-table
-table.concat
-table.insert
-table.move
-table.pack
-table.remove
-table.sort
-table.unpack
- -

-utf8
-utf8.char
-utf8.charpattern
-utf8.codepoint
-utf8.codes
-utf8.len
-utf8.offset
- -

environment
variables

-

-LUA_CPATH
-LUA_CPATH_5_3
-LUA_INIT
-LUA_INIT_5_3
-LUA_PATH
-LUA_PATH_5_3
- -

 -

C API

-

-lua_Alloc
-lua_CFunction
-lua_Debug
-lua_Hook
-lua_Integer
-lua_KContext
-lua_KFunction
-lua_Number
-lua_Reader
-lua_State
-lua_Unsigned
-lua_Writer
- -

-lua_absindex
-lua_arith
-lua_atpanic
-lua_call
-lua_callk
-lua_checkstack
-lua_close
-lua_compare
-lua_concat
-lua_copy
-lua_createtable
-lua_dump
-lua_error
-lua_gc
-lua_getallocf
-lua_getextraspace
-lua_getfield
-lua_getglobal
-lua_gethook
-lua_gethookcount
-lua_gethookmask
-lua_geti
-lua_getinfo
-lua_getlocal
-lua_getmetatable
-lua_getstack
-lua_gettable
-lua_gettop
-lua_getupvalue
-lua_getuservalue
-lua_insert
-lua_isboolean
-lua_iscfunction
-lua_isfunction
-lua_isinteger
-lua_islightuserdata
-lua_isnil
-lua_isnone
-lua_isnoneornil
-lua_isnumber
-lua_isstring
-lua_istable
-lua_isthread
-lua_isuserdata
-lua_isyieldable
-lua_len
-lua_load
-lua_newstate
-lua_newtable
-lua_newthread
-lua_newuserdata
-lua_next
-lua_numbertointeger
-lua_pcall
-lua_pcallk
-lua_pop
-lua_pushboolean
-lua_pushcclosure
-lua_pushcfunction
-lua_pushfstring
-lua_pushglobaltable
-lua_pushinteger
-lua_pushlightuserdata
-lua_pushliteral
-lua_pushlstring
-lua_pushnil
-lua_pushnumber
-lua_pushstring
-lua_pushthread
-lua_pushvalue
-lua_pushvfstring
-lua_rawequal
-lua_rawget
-lua_rawgeti
-lua_rawgetp
-lua_rawlen
-lua_rawset
-lua_rawseti
-lua_rawsetp
-lua_register
-lua_remove
-lua_replace
-lua_resume
-lua_rotate
-lua_setallocf
-lua_setfield
-lua_setglobal
-lua_sethook
-lua_seti
-lua_setlocal
-lua_setmetatable
-lua_settable
-lua_settop
-lua_setupvalue
-lua_setuservalue
-lua_status
-lua_stringtonumber
-lua_toboolean
-lua_tocfunction
-lua_tointeger
-lua_tointegerx
-lua_tolstring
-lua_tonumber
-lua_tonumberx
-lua_topointer
-lua_tostring
-lua_tothread
-lua_touserdata
-lua_type
-lua_typename
-lua_upvalueid
-lua_upvalueindex
-lua_upvaluejoin
-lua_version
-lua_xmove
-lua_yield
-lua_yieldk
- -

 -

auxiliary library

-

-luaL_Buffer
-luaL_Reg
-luaL_Stream
- -

-luaL_addchar
-luaL_addlstring
-luaL_addsize
-luaL_addstring
-luaL_addvalue
-luaL_argcheck
-luaL_argerror
-luaL_buffinit
-luaL_buffinitsize
-luaL_callmeta
-luaL_checkany
-luaL_checkinteger
-luaL_checklstring
-luaL_checknumber
-luaL_checkoption
-luaL_checkstack
-luaL_checkstring
-luaL_checktype
-luaL_checkudata
-luaL_checkversion
-luaL_dofile
-luaL_dostring
-luaL_error
-luaL_execresult
-luaL_fileresult
-luaL_getmetafield
-luaL_getmetatable
-luaL_getsubtable
-luaL_gsub
-luaL_len
-luaL_loadbuffer
-luaL_loadbufferx
-luaL_loadfile
-luaL_loadfilex
-luaL_loadstring
-luaL_newlib
-luaL_newlibtable
-luaL_newmetatable
-luaL_newstate
-luaL_openlibs
-luaL_opt
-luaL_optinteger
-luaL_optlstring
-luaL_optnumber
-luaL_optstring
-luaL_prepbuffer
-luaL_prepbuffsize
-luaL_pushresult
-luaL_pushresultsize
-luaL_ref
-luaL_requiref
-luaL_setfuncs
-luaL_setmetatable
-luaL_testudata
-luaL_tolstring
-luaL_traceback
-luaL_typename
-luaL_unref
-luaL_where
- -

standard library

-

-luaopen_base
-luaopen_coroutine
-luaopen_debug
-luaopen_io
-luaopen_math
-luaopen_os
-luaopen_package
-luaopen_string
-luaopen_table
-luaopen_utf8
- -

constants

-

-LUA_ERRERR
-LUA_ERRFILE
-LUA_ERRGCMM
-LUA_ERRMEM
-LUA_ERRRUN
-LUA_ERRSYNTAX
-LUA_HOOKCALL
-LUA_HOOKCOUNT
-LUA_HOOKLINE
-LUA_HOOKRET
-LUA_HOOKTAILCALL
-LUA_MASKCALL
-LUA_MASKCOUNT
-LUA_MASKLINE
-LUA_MASKRET
-LUA_MAXINTEGER
-LUA_MININTEGER
-LUA_MINSTACK
-LUA_MULTRET
-LUA_NOREF
-LUA_OK
-LUA_OPADD
-LUA_OPBAND
-LUA_OPBNOT
-LUA_OPBOR
-LUA_OPBXOR
-LUA_OPDIV
-LUA_OPEQ
-LUA_OPIDIV
-LUA_OPLE
-LUA_OPLT
-LUA_OPMOD
-LUA_OPMUL
-LUA_OPPOW
-LUA_OPSHL
-LUA_OPSHR
-LUA_OPSUB
-LUA_OPUNM
-LUA_REFNIL
-LUA_REGISTRYINDEX
-LUA_RIDX_GLOBALS
-LUA_RIDX_MAINTHREAD
-LUA_TBOOLEAN
-LUA_TFUNCTION
-LUA_TLIGHTUSERDATA
-LUA_TNIL
-LUA_TNONE
-LUA_TNUMBER
-LUA_TSTRING
-LUA_TTABLE
-LUA_TTHREAD
-LUA_TUSERDATA
-LUA_USE_APICHECK
-LUA_YIELD
-LUAL_BUFFERSIZE
- -

- -

-Last update: -Mon Jun 18 22:56:06 -03 2018 -

- - - - diff --git a/libs/liblua/docs/index.css b/libs/liblua/docs/index.css deleted file mode 100644 index c961835731..0000000000 --- a/libs/liblua/docs/index.css +++ /dev/null @@ -1,21 +0,0 @@ -ul { - list-style-type: none ; -} - -ul.contents { - padding: 0 ; -} - -table { - border: none ; - border-spacing: 0 ; - border-collapse: collapse ; -} - -td { - vertical-align: top ; - padding: 0 ; - text-align: left ; - line-height: 1.25 ; - width: 15% ; -} diff --git a/libs/liblua/docs/manual.css b/libs/liblua/docs/manual.css deleted file mode 100644 index aa0e677dd5..0000000000 --- a/libs/liblua/docs/manual.css +++ /dev/null @@ -1,21 +0,0 @@ -h3 code { - font-family: inherit ; - font-size: inherit ; -} - -pre, code { - font-size: 12pt ; -} - -span.apii { - color: gray ; - float: right ; - font-family: inherit ; - font-style: normal ; - font-size: small ; -} - -h2:before { - content: "" ; - padding-right: 0em ; -} diff --git a/libs/liblua/docs/manual.html b/libs/liblua/docs/manual.html deleted file mode 100644 index 89a642a45d..0000000000 --- a/libs/liblua/docs/manual.html +++ /dev/null @@ -1,10982 +0,0 @@ - - - -Lua 5.3 Reference Manual - - - - - - - -

-Lua -Lua 5.3 Reference Manual -

- -

-by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes - -

- -Copyright © 2015–2018 Lua.org, PUC-Rio. -Freely available under the terms of the -Lua license. - - -

-contents -· -index -· -other versions -
- - -

- - - - - - -

1 – Introduction

- -

-Lua is a powerful, efficient, lightweight, embeddable scripting language. -It supports procedural programming, -object-oriented programming, functional programming, -data-driven programming, and data description. - - -

-Lua combines simple procedural syntax with powerful data description -constructs based on associative arrays and extensible semantics. -Lua is dynamically typed, -runs by interpreting bytecode with a register-based -virtual machine, -and has automatic memory management with -incremental garbage collection, -making it ideal for configuration, scripting, -and rapid prototyping. - - -

-Lua is implemented as a library, written in clean C, -the common subset of Standard C and C++. -The Lua distribution includes a host program called lua, -which uses the Lua library to offer a complete, -standalone Lua interpreter, -for interactive or batch use. -Lua is intended to be used both as a powerful, lightweight, -embeddable scripting language for any program that needs one, -and as a powerful but lightweight and efficient stand-alone language. - - -

-As an extension language, Lua has no notion of a "main" program: -it works embedded in a host client, -called the embedding program or simply the host. -(Frequently, this host is the stand-alone lua program.) -The host program can invoke functions to execute a piece of Lua code, -can write and read Lua variables, -and can register C functions to be called by Lua code. -Through the use of C functions, Lua can be augmented to cope with -a wide range of different domains, -thus creating customized programming languages sharing a syntactical framework. - - -

-Lua is free software, -and is provided as usual with no guarantees, -as stated in its license. -The implementation described in this manual is available -at Lua's official web site, www.lua.org. - - -

-Like any other reference manual, -this document is dry in places. -For a discussion of the decisions behind the design of Lua, -see the technical papers available at Lua's web site. -For a detailed introduction to programming in Lua, -see Roberto's book, Programming in Lua. - - - -

2 – Basic Concepts

- -

-This section describes the basic concepts of the language. - - - -

2.1 – Values and Types

- -

-Lua is a dynamically typed language. -This means that -variables do not have types; only values do. -There are no type definitions in the language. -All values carry their own type. - - -

-All values in Lua are first-class values. -This means that all values can be stored in variables, -passed as arguments to other functions, and returned as results. - - -

-There are eight basic types in Lua: -nil, boolean, number, -string, function, userdata, -thread, and table. -The type nil has one single value, nil, -whose main property is to be different from any other value; -it usually represents the absence of a useful value. -The type boolean has two values, false and true. -Both nil and false make a condition false; -any other value makes it true. -The type number represents both -integer numbers and real (floating-point) numbers. -The type string represents immutable sequences of bytes. - -Lua is 8-bit clean: -strings can contain any 8-bit value, -including embedded zeros ('\0'). -Lua is also encoding-agnostic; -it makes no assumptions about the contents of a string. - - -

-The type number uses two internal representations, -or two subtypes, -one called integer and the other called float. -Lua has explicit rules about when each representation is used, -but it also converts between them automatically as needed (see §3.4.3). -Therefore, -the programmer may choose to mostly ignore the difference -between integers and floats -or to assume complete control over the representation of each number. -Standard Lua uses 64-bit integers and double-precision (64-bit) floats, -but you can also compile Lua so that it -uses 32-bit integers and/or single-precision (32-bit) floats. -The option with 32 bits for both integers and floats -is particularly attractive -for small machines and embedded systems. -(See macro LUA_32BITS in file luaconf.h.) - - -

-Lua can call (and manipulate) functions written in Lua and -functions written in C (see §3.4.10). -Both are represented by the type function. - - -

-The type userdata is provided to allow arbitrary C data to -be stored in Lua variables. -A userdata value represents a block of raw memory. -There are two kinds of userdata: -full userdata, -which is an object with a block of memory managed by Lua, -and light userdata, -which is simply a C pointer value. -Userdata has no predefined operations in Lua, -except assignment and identity test. -By using metatables, -the programmer can define operations for full userdata values -(see §2.4). -Userdata values cannot be created or modified in Lua, -only through the C API. -This guarantees the integrity of data owned by the host program. - - -

-The type thread represents independent threads of execution -and it is used to implement coroutines (see §2.6). -Lua threads are not related to operating-system threads. -Lua supports coroutines on all systems, -even those that do not support threads natively. - - -

-The type table implements associative arrays, -that is, arrays that can have as indices not only numbers, -but any Lua value except nil and NaN. -(Not a Number is a special value used to represent -undefined or unrepresentable numerical results, such as 0/0.) -Tables can be heterogeneous; -that is, they can contain values of all types (except nil). -Any key with value nil is not considered part of the table. -Conversely, any key that is not part of a table has -an associated value nil. - - -

-Tables are the sole data-structuring mechanism in Lua; -they can be used to represent ordinary arrays, lists, -symbol tables, sets, records, graphs, trees, etc. -To represent records, Lua uses the field name as an index. -The language supports this representation by -providing a.name as syntactic sugar for a["name"]. -There are several convenient ways to create tables in Lua -(see §3.4.9). - - -

-Like indices, -the values of table fields can be of any type. -In particular, -because functions are first-class values, -table fields can contain functions. -Thus tables can also carry methods (see §3.4.11). - - -

-The indexing of tables follows -the definition of raw equality in the language. -The expressions a[i] and a[j] -denote the same table element -if and only if i and j are raw equal -(that is, equal without metamethods). -In particular, floats with integral values -are equal to their respective integers -(e.g., 1.0 == 1). -To avoid ambiguities, -any float with integral value used as a key -is converted to its respective integer. -For instance, if you write a[2.0] = true, -the actual key inserted into the table will be the -integer 2. -(On the other hand, -2 and "2" are different Lua values and therefore -denote different table entries.) - - -

-Tables, functions, threads, and (full) userdata values are objects: -variables do not actually contain these values, -only references to them. -Assignment, parameter passing, and function returns -always manipulate references to such values; -these operations do not imply any kind of copy. - - -

-The library function type returns a string describing the type -of a given value (see §6.1). - - - - - -

2.2 – Environments and the Global Environment

- -

-As will be discussed in §3.2 and §3.3.3, -any reference to a free name -(that is, a name not bound to any declaration) var -is syntactically translated to _ENV.var. -Moreover, every chunk is compiled in the scope of -an external local variable named _ENV (see §3.3.2), -so _ENV itself is never a free name in a chunk. - - -

-Despite the existence of this external _ENV variable and -the translation of free names, -_ENV is a completely regular name. -In particular, -you can define new variables and parameters with that name. -Each reference to a free name uses the _ENV that is -visible at that point in the program, -following the usual visibility rules of Lua (see §3.5). - - -

-Any table used as the value of _ENV is called an environment. - - -

-Lua keeps a distinguished environment called the global environment. -This value is kept at a special index in the C registry (see §4.5). -In Lua, the global variable _G is initialized with this same value. -(_G is never used internally.) - - -

-When Lua loads a chunk, -the default value for its _ENV upvalue -is the global environment (see load). -Therefore, by default, -free names in Lua code refer to entries in the global environment -(and, therefore, they are also called global variables). -Moreover, all standard libraries are loaded in the global environment -and some functions there operate on that environment. -You can use load (or loadfile) -to load a chunk with a different environment. -(In C, you have to load the chunk and then change the value -of its first upvalue.) - - - - - -

2.3 – Error Handling

- -

-Because Lua is an embedded extension language, -all Lua actions start from C code in the host program -calling a function from the Lua library. -(When you use Lua standalone, -the lua application is the host program.) -Whenever an error occurs during -the compilation or execution of a Lua chunk, -control returns to the host, -which can take appropriate measures -(such as printing an error message). - - -

-Lua code can explicitly generate an error by calling the -error function. -If you need to catch errors in Lua, -you can use pcall or xpcall -to call a given function in protected mode. - - -

-Whenever there is an error, -an error object (also called an error message) -is propagated with information about the error. -Lua itself only generates errors whose error object is a string, -but programs may generate errors with -any value as the error object. -It is up to the Lua program or its host to handle such error objects. - - -

-When you use xpcall or lua_pcall, -you may give a message handler -to be called in case of errors. -This function is called with the original error object -and returns a new error object. -It is called before the error unwinds the stack, -so that it can gather more information about the error, -for instance by inspecting the stack and creating a stack traceback. -This message handler is still protected by the protected call; -so, an error inside the message handler -will call the message handler again. -If this loop goes on for too long, -Lua breaks it and returns an appropriate message. -(The message handler is called only for regular runtime errors. -It is not called for memory-allocation errors -nor for errors while running finalizers.) - - - - - -

2.4 – Metatables and Metamethods

- -

-Every value in Lua can have a metatable. -This metatable is an ordinary Lua table -that defines the behavior of the original value -under certain special operations. -You can change several aspects of the behavior -of operations over a value by setting specific fields in its metatable. -For instance, when a non-numeric value is the operand of an addition, -Lua checks for a function in the field "__add" of the value's metatable. -If it finds one, -Lua calls this function to perform the addition. - - -

-The key for each event in a metatable is a string -with the event name prefixed by two underscores; -the corresponding values are called metamethods. -In the previous example, the key is "__add" -and the metamethod is the function that performs the addition. -Unless stated otherwise, -metamethods should be function values. - - -

-You can query the metatable of any value -using the getmetatable function. -Lua queries metamethods in metatables using a raw access (see rawget). -So, to retrieve the metamethod for event ev in object o, -Lua does the equivalent to the following code: - -

-     rawget(getmetatable(o) or {}, "__ev")
-
- -

-You can replace the metatable of tables -using the setmetatable function. -You cannot change the metatable of other types from Lua code -(except by using the debug library (§6.10)); -you should use the C API for that. - - -

-Tables and full userdata have individual metatables -(although multiple tables and userdata can share their metatables). -Values of all other types share one single metatable per type; -that is, there is one single metatable for all numbers, -one for all strings, etc. -By default, a value has no metatable, -but the string library sets a metatable for the string type (see §6.4). - - -

-A metatable controls how an object behaves in -arithmetic operations, bitwise operations, -order comparisons, concatenation, length operation, calls, and indexing. -A metatable also can define a function to be called -when a userdata or a table is garbage collected (§2.5). - - -

-For the unary operators (negation, length, and bitwise NOT), -the metamethod is computed and called with a dummy second operand, -equal to the first one. -This extra operand is only to simplify Lua's internals -(by making these operators behave like a binary operation) -and may be removed in future versions. -(For most uses this extra operand is irrelevant.) - - -

-A detailed list of events controlled by metatables is given next. -Each operation is identified by its corresponding key. - - - -

    - -
  • __add: -the addition (+) operation. -If any operand for an addition is not a number -(nor a string coercible to a number), -Lua will try to call a metamethod. -First, Lua will check the first operand (even if it is valid). -If that operand does not define a metamethod for __add, -then Lua will check the second operand. -If Lua can find a metamethod, -it calls the metamethod with the two operands as arguments, -and the result of the call -(adjusted to one value) -is the result of the operation. -Otherwise, -it raises an error. -
    • - -
  • __sub: -the subtraction (-) operation. -Behavior similar to the addition operation. -
    • - -
  • __mul: -the multiplication (*) operation. -Behavior similar to the addition operation. -
    • - -
  • __div: -the division (/) operation. -Behavior similar to the addition operation. -
    • - -
  • __mod: -the modulo (%) operation. -Behavior similar to the addition operation. -
    • - -
  • __pow: -the exponentiation (^) operation. -Behavior similar to the addition operation. -
    • - -
  • __unm: -the negation (unary -) operation. -Behavior similar to the addition operation. -
    • - -
  • __idiv: -the floor division (//) operation. -Behavior similar to the addition operation. -
    • - -
  • __band: -the bitwise AND (&) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod -if any operand is neither an integer -nor a value coercible to an integer (see §3.4.3). -
    • - -
  • __bor: -the bitwise OR (|) operation. -Behavior similar to the bitwise AND operation. -
    • - -
  • __bxor: -the bitwise exclusive OR (binary ~) operation. -Behavior similar to the bitwise AND operation. -
    • - -
  • __bnot: -the bitwise NOT (unary ~) operation. -Behavior similar to the bitwise AND operation. -
    • - -
  • __shl: -the bitwise left shift (<<) operation. -Behavior similar to the bitwise AND operation. -
    • - -
  • __shr: -the bitwise right shift (>>) operation. -Behavior similar to the bitwise AND operation. -
    • - -
  • __concat: -the concatenation (..) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod -if any operand is neither a string nor a number -(which is always coercible to a string). -
    • - -
  • __len: -the length (#) operation. -If the object is not a string, -Lua will try its metamethod. -If there is a metamethod, -Lua calls it with the object as argument, -and the result of the call -(always adjusted to one value) -is the result of the operation. -If there is no metamethod but the object is a table, -then Lua uses the table length operation (see §3.4.7). -Otherwise, Lua raises an error. -
    • - -
  • __eq: -the equal (==) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod only when the values -being compared are either both tables or both full userdata -and they are not primitively equal. -The result of the call is always converted to a boolean. -
    • - -
  • __lt: -the less than (<) operation. -Behavior similar to the addition operation, -except that Lua will try a metamethod only when the values -being compared are neither both numbers nor both strings. -The result of the call is always converted to a boolean. -
    • - -
  • __le: -the less equal (<=) operation. -Unlike other operations, -the less-equal operation can use two different events. -First, Lua looks for the __le metamethod in both operands, -like in the less than operation. -If it cannot find such a metamethod, -then it will try the __lt metamethod, -assuming that a <= b is equivalent to not (b < a). -As with the other comparison operators, -the result is always a boolean. -(This use of the __lt event can be removed in future versions; -it is also slower than a real __le metamethod.) -
    • - -
  • __index: -The indexing access operation table[key]. -This event happens when table is not a table or -when key is not present in table. -The metamethod is looked up in table. - - -

    -Despite the name, -the metamethod for this event can be either a function or a table. -If it is a function, -it is called with table and key as arguments, -and the result of the call -(adjusted to one value) -is the result of the operation. -If it is a table, -the final result is the result of indexing this table with key. -(This indexing is regular, not raw, -and therefore can trigger another metamethod.) -

    • - -
  • __newindex: -The indexing assignment table[key] = value. -Like the index event, -this event happens when table is not a table or -when key is not present in table. -The metamethod is looked up in table. - - -

    -Like with indexing, -the metamethod for this event can be either a function or a table. -If it is a function, -it is called with table, key, and value as arguments. -If it is a table, -Lua does an indexing assignment to this table with the same key and value. -(This assignment is regular, not raw, -and therefore can trigger another metamethod.) - - -

    -Whenever there is a __newindex metamethod, -Lua does not perform the primitive assignment. -(If necessary, -the metamethod itself can call rawset -to do the assignment.) -

    • - -
  • __call: -The call operation func(args). -This event happens when Lua tries to call a non-function value -(that is, func is not a function). -The metamethod is looked up in func. -If present, -the metamethod is called with func as its first argument, -followed by the arguments of the original call (args). -All results of the call -are the result of the operation. -(This is the only metamethod that allows multiple results.) -
    • - -
- -

-It is a good practice to add all needed metamethods to a table -before setting it as a metatable of some object. -In particular, the __gc metamethod works only when this order -is followed (see §2.5.1). - - -

-Because metatables are regular tables, -they can contain arbitrary fields, -not only the event names defined above. -Some functions in the standard library -(e.g., tostring) -use other fields in metatables for their own purposes. - - - - - -

2.5 – Garbage Collection

- -

-Lua performs automatic memory management. -This means that -you do not have to worry about allocating memory for new objects -or freeing it when the objects are no longer needed. -Lua manages memory automatically by running -a garbage collector to collect all dead objects -(that is, objects that are no longer accessible from Lua). -All memory used by Lua is subject to automatic management: -strings, tables, userdata, functions, threads, internal structures, etc. - - -

-Lua implements an incremental mark-and-sweep collector. -It uses two numbers to control its garbage-collection cycles: -the garbage-collector pause and -the garbage-collector step multiplier. -Both use percentage points as units -(e.g., a value of 100 means an internal value of 1). - - -

-The garbage-collector pause -controls how long the collector waits before starting a new cycle. -Larger values make the collector less aggressive. -Values smaller than 100 mean the collector will not wait to -start a new cycle. -A value of 200 means that the collector waits for the total memory in use -to double before starting a new cycle. - - -

-The garbage-collector step multiplier -controls the relative speed of the collector relative to -memory allocation. -Larger values make the collector more aggressive but also increase -the size of each incremental step. -You should not use values smaller than 100, -because they make the collector too slow and -can result in the collector never finishing a cycle. -The default is 200, -which means that the collector runs at "twice" -the speed of memory allocation. - - -

-If you set the step multiplier to a very large number -(larger than 10% of the maximum number of -bytes that the program may use), -the collector behaves like a stop-the-world collector. -If you then set the pause to 200, -the collector behaves as in old Lua versions, -doing a complete collection every time Lua doubles its -memory usage. - - -

-You can change these numbers by calling lua_gc in C -or collectgarbage in Lua. -You can also use these functions to control -the collector directly (e.g., stop and restart it). - - - -

2.5.1 – Garbage-Collection Metamethods

- -

-You can set garbage-collector metamethods for tables -and, using the C API, -for full userdata (see §2.4). -These metamethods are also called finalizers. -Finalizers allow you to coordinate Lua's garbage collection -with external resource management -(such as closing files, network or database connections, -or freeing your own memory). - - -

-For an object (table or userdata) to be finalized when collected, -you must mark it for finalization. - -You mark an object for finalization when you set its metatable -and the metatable has a field indexed by the string "__gc". -Note that if you set a metatable without a __gc field -and later create that field in the metatable, -the object will not be marked for finalization. - - -

-When a marked object becomes garbage, -it is not collected immediately by the garbage collector. -Instead, Lua puts it in a list. -After the collection, -Lua goes through that list. -For each object in the list, -it checks the object's __gc metamethod: -If it is a function, -Lua calls it with the object as its single argument; -if the metamethod is not a function, -Lua simply ignores it. - - -

-At the end of each garbage-collection cycle, -the finalizers for objects are called in -the reverse order that the objects were marked for finalization, -among those collected in that cycle; -that is, the first finalizer to be called is the one associated -with the object marked last in the program. -The execution of each finalizer may occur at any point during -the execution of the regular code. - - -

-Because the object being collected must still be used by the finalizer, -that object (and other objects accessible only through it) -must be resurrected by Lua. -Usually, this resurrection is transient, -and the object memory is freed in the next garbage-collection cycle. -However, if the finalizer stores the object in some global place -(e.g., a global variable), -then the resurrection is permanent. -Moreover, if the finalizer marks a finalizing object for finalization again, -its finalizer will be called again in the next cycle where the -object is unreachable. -In any case, -the object memory is freed only in a GC cycle where -the object is unreachable and not marked for finalization. - - -

-When you close a state (see lua_close), -Lua calls the finalizers of all objects marked for finalization, -following the reverse order that they were marked. -If any finalizer marks objects for collection during that phase, -these marks have no effect. - - - - - -

2.5.2 – Weak Tables

- -

-A weak table is a table whose elements are -weak references. -A weak reference is ignored by the garbage collector. -In other words, -if the only references to an object are weak references, -then the garbage collector will collect that object. - - -

-A weak table can have weak keys, weak values, or both. -A table with weak values allows the collection of its values, -but prevents the collection of its keys. -A table with both weak keys and weak values allows the collection of -both keys and values. -In any case, if either the key or the value is collected, -the whole pair is removed from the table. -The weakness of a table is controlled by the -__mode field of its metatable. -If the __mode field is a string containing the character 'k', -the keys in the table are weak. -If __mode contains 'v', -the values in the table are weak. - - -

-A table with weak keys and strong values -is also called an ephemeron table. -In an ephemeron table, -a value is considered reachable only if its key is reachable. -In particular, -if the only reference to a key comes through its value, -the pair is removed. - - -

-Any change in the weakness of a table may take effect only -at the next collect cycle. -In particular, if you change the weakness to a stronger mode, -Lua may still collect some items from that table -before the change takes effect. - - -

-Only objects that have an explicit construction -are removed from weak tables. -Values, such as numbers and light C functions, -are not subject to garbage collection, -and therefore are not removed from weak tables -(unless their associated values are collected). -Although strings are subject to garbage collection, -they do not have an explicit construction, -and therefore are not removed from weak tables. - - -

-Resurrected objects -(that is, objects being finalized -and objects accessible only through objects being finalized) -have a special behavior in weak tables. -They are removed from weak values before running their finalizers, -but are removed from weak keys only in the next collection -after running their finalizers, when such objects are actually freed. -This behavior allows the finalizer to access properties -associated with the object through weak tables. - - -

-If a weak table is among the resurrected objects in a collection cycle, -it may not be properly cleared until the next cycle. - - - - - - - -

2.6 – Coroutines

- -

-Lua supports coroutines, -also called collaborative multithreading. -A coroutine in Lua represents an independent thread of execution. -Unlike threads in multithread systems, however, -a coroutine only suspends its execution by explicitly calling -a yield function. - - -

-You create a coroutine by calling coroutine.create. -Its sole argument is a function -that is the main function of the coroutine. -The create function only creates a new coroutine and -returns a handle to it (an object of type thread); -it does not start the coroutine. - - -

-You execute a coroutine by calling coroutine.resume. -When you first call coroutine.resume, -passing as its first argument -a thread returned by coroutine.create, -the coroutine starts its execution by -calling its main function. -Extra arguments passed to coroutine.resume are passed -as arguments to that function. -After the coroutine starts running, -it runs until it terminates or yields. - - -

-A coroutine can terminate its execution in two ways: -normally, when its main function returns -(explicitly or implicitly, after the last instruction); -and abnormally, if there is an unprotected error. -In case of normal termination, -coroutine.resume returns true, -plus any values returned by the coroutine main function. -In case of errors, coroutine.resume returns false -plus an error object. - - -

-A coroutine yields by calling coroutine.yield. -When a coroutine yields, -the corresponding coroutine.resume returns immediately, -even if the yield happens inside nested function calls -(that is, not in the main function, -but in a function directly or indirectly called by the main function). -In the case of a yield, coroutine.resume also returns true, -plus any values passed to coroutine.yield. -The next time you resume the same coroutine, -it continues its execution from the point where it yielded, -with the call to coroutine.yield returning any extra -arguments passed to coroutine.resume. - - -

-Like coroutine.create, -the coroutine.wrap function also creates a coroutine, -but instead of returning the coroutine itself, -it returns a function that, when called, resumes the coroutine. -Any arguments passed to this function -go as extra arguments to coroutine.resume. -coroutine.wrap returns all the values returned by coroutine.resume, -except the first one (the boolean error code). -Unlike coroutine.resume, -coroutine.wrap does not catch errors; -any error is propagated to the caller. - - -

-As an example of how coroutines work, -consider the following code: - -

-     function foo (a)
-       print("foo", a)
-       return coroutine.yield(2*a)
-     end
-     
-     co = coroutine.create(function (a,b)
-           print("co-body", a, b)
-           local r = foo(a+1)
-           print("co-body", r)
-           local r, s = coroutine.yield(a+b, a-b)
-           print("co-body", r, s)
-           return b, "end"
-     end)
-     
-     print("main", coroutine.resume(co, 1, 10))
-     print("main", coroutine.resume(co, "r"))
-     print("main", coroutine.resume(co, "x", "y"))
-     print("main", coroutine.resume(co, "x", "y"))
-

-When you run it, it produces the following output: - -

-     co-body 1       10
-     foo     2
-     main    true    4
-     co-body r
-     main    true    11      -9
-     co-body x       y
-     main    true    10      end
-     main    false   cannot resume dead coroutine
-
- -

-You can also create and manipulate coroutines through the C API: -see functions lua_newthread, lua_resume, -and lua_yield. - - - - - -

3 – The Language

- -

-This section describes the lexis, the syntax, and the semantics of Lua. -In other words, -this section describes -which tokens are valid, -how they can be combined, -and what their combinations mean. - - -

-Language constructs will be explained using the usual extended BNF notation, -in which -{a} means 0 or more a's, and -[a] means an optional a. -Non-terminals are shown like non-terminal, -keywords are shown like kword, -and other terminal symbols are shown like ‘=’. -The complete syntax of Lua can be found in §9 -at the end of this manual. - - - -

3.1 – Lexical Conventions

- -

-Lua is a free-form language. -It ignores spaces (including new lines) and comments -between lexical elements (tokens), -except as delimiters between names and keywords. - - -

-Names -(also called identifiers) -in Lua can be any string of letters, -digits, and underscores, -not beginning with a digit and -not being a reserved word. -Identifiers are used to name variables, table fields, and labels. - - -

-The following keywords are reserved -and cannot be used as names: - - -

-     and       break     do        else      elseif    end
-     false     for       function  goto      if        in
-     local     nil       not       or        repeat    return
-     then      true      until     while
-
- -

-Lua is a case-sensitive language: -and is a reserved word, but And and AND -are two different, valid names. -As a convention, -programs should avoid creating -names that start with an underscore followed by -one or more uppercase letters (such as _VERSION). - - -

-The following strings denote other tokens: - -

-     +     -     *     /     %     ^     #
-     &     ~     |     <<    >>    //
-     ==    ~=    <=    >=    <     >     =
-     (     )     {     }     [     ]     ::
-     ;     :     ,     .     ..    ...
-
- -

-A short literal string -can be delimited by matching single or double quotes, -and can contain the following C-like escape sequences: -'\a' (bell), -'\b' (backspace), -'\f' (form feed), -'\n' (newline), -'\r' (carriage return), -'\t' (horizontal tab), -'\v' (vertical tab), -'\\' (backslash), -'\"' (quotation mark [double quote]), -and '\'' (apostrophe [single quote]). -A backslash followed by a line break -results in a newline in the string. -The escape sequence '\z' skips the following span -of white-space characters, -including line breaks; -it is particularly useful to break and indent a long literal string -into multiple lines without adding the newlines and spaces -into the string contents. -A short literal string cannot contain unescaped line breaks -nor escapes not forming a valid escape sequence. - - -

-We can specify any byte in a short literal string by its numeric value -(including embedded zeros). -This can be done -with the escape sequence \xXX, -where XX is a sequence of exactly two hexadecimal digits, -or with the escape sequence \ddd, -where ddd is a sequence of up to three decimal digits. -(Note that if a decimal escape sequence is to be followed by a digit, -it must be expressed using exactly three digits.) - - -

-The UTF-8 encoding of a Unicode character -can be inserted in a literal string with -the escape sequence \u{XXX} -(note the mandatory enclosing brackets), -where XXX is a sequence of one or more hexadecimal digits -representing the character code point. - - -

-Literal strings can also be defined using a long format -enclosed by long brackets. -We define an opening long bracket of level n as an opening -square bracket followed by n equal signs followed by another -opening square bracket. -So, an opening long bracket of level 0 is written as [[, -an opening long bracket of level 1 is written as [=[, -and so on. -A closing long bracket is defined similarly; -for instance, -a closing long bracket of level 4 is written as ]====]. -A long literal starts with an opening long bracket of any level and -ends at the first closing long bracket of the same level. -It can contain any text except a closing bracket of the same level. -Literals in this bracketed form can run for several lines, -do not interpret any escape sequences, -and ignore long brackets of any other level. -Any kind of end-of-line sequence -(carriage return, newline, carriage return followed by newline, -or newline followed by carriage return) -is converted to a simple newline. - - -

-For convenience, -when the opening long bracket is immediately followed by a newline, -the newline is not included in the string. -As an example, in a system using ASCII -(in which 'a' is coded as 97, -newline is coded as 10, and '1' is coded as 49), -the five literal strings below denote the same string: - -

-     a = 'alo\n123"'
-     a = "alo\n123\""
-     a = '\97lo\10\04923"'
-     a = [[alo
-     123"]]
-     a = [==[
-     alo
-     123"]==]
-
- -

-Any byte in a literal string not -explicitly affected by the previous rules represents itself. -However, Lua opens files for parsing in text mode, -and the system file functions may have problems with -some control characters. -So, it is safer to represent -non-text data as a quoted literal with -explicit escape sequences for the non-text characters. - - -

-A numeric constant (or numeral) -can be written with an optional fractional part -and an optional decimal exponent, -marked by a letter 'e' or 'E'. -Lua also accepts hexadecimal constants, -which start with 0x or 0X. -Hexadecimal constants also accept an optional fractional part -plus an optional binary exponent, -marked by a letter 'p' or 'P'. -A numeric constant with a radix point or an exponent -denotes a float; -otherwise, -if its value fits in an integer, -it denotes an integer. -Examples of valid integer constants are - -

-     3   345   0xff   0xBEBADA
-

-Examples of valid float constants are - -

-     3.0     3.1416     314.16e-2     0.31416E1     34e1
-     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
-
- -

-A comment starts with a double hyphen (--) -anywhere outside a string. -If the text immediately after -- is not an opening long bracket, -the comment is a short comment, -which runs until the end of the line. -Otherwise, it is a long comment, -which runs until the corresponding closing long bracket. -Long comments are frequently used to disable code temporarily. - - - - - -

3.2 – Variables

- -

-Variables are places that store values. -There are three kinds of variables in Lua: -global variables, local variables, and table fields. - - -

-A single name can denote a global variable or a local variable -(or a function's formal parameter, -which is a particular kind of local variable): - -

-	var ::= Name
-

-Name denotes identifiers, as defined in §3.1. - - -

-Any variable name is assumed to be global unless explicitly declared -as a local (see §3.3.7). -Local variables are lexically scoped: -local variables can be freely accessed by functions -defined inside their scope (see §3.5). - - -

-Before the first assignment to a variable, its value is nil. - - -

-Square brackets are used to index a table: - -

-	var ::= prefixexp ‘[’ exp ‘]’
-

-The meaning of accesses to table fields can be changed via metatables -(see §2.4). - - -

-The syntax var.Name is just syntactic sugar for -var["Name"]: - -

-	var ::= prefixexp ‘.’ Name
-
- -

-An access to a global variable x -is equivalent to _ENV.x. -Due to the way that chunks are compiled, -_ENV is never a global name (see §2.2). - - - - - -

3.3 – Statements

- -

-Lua supports an almost conventional set of statements, -similar to those in Pascal or C. -This set includes -assignments, control structures, function calls, -and variable declarations. - - - -

3.3.1 – Blocks

- -

-A block is a list of statements, -which are executed sequentially: - -

-	block ::= {stat}
-

-Lua has empty statements -that allow you to separate statements with semicolons, -start a block with a semicolon -or write two semicolons in sequence: - -

-	stat ::= ‘;’
-
- -

-Function calls and assignments -can start with an open parenthesis. -This possibility leads to an ambiguity in Lua's grammar. -Consider the following fragment: - -

-     a = b + c
-     (print or io.write)('done')
-

-The grammar could see it in two ways: - -

-     a = b + c(print or io.write)('done')
-     
-     a = b + c; (print or io.write)('done')
-

-The current parser always sees such constructions -in the first way, -interpreting the open parenthesis -as the start of the arguments to a call. -To avoid this ambiguity, -it is a good practice to always precede with a semicolon -statements that start with a parenthesis: - -

-     ;(print or io.write)('done')
-
- -

-A block can be explicitly delimited to produce a single statement: - -

-	stat ::= do block end
-

-Explicit blocks are useful -to control the scope of variable declarations. -Explicit blocks are also sometimes used to -add a return statement in the middle -of another block (see §3.3.4). - - - - - -

3.3.2 – Chunks

- -

-The unit of compilation of Lua is called a chunk. -Syntactically, -a chunk is simply a block: - -

-	chunk ::= block
-
- -

-Lua handles a chunk as the body of an anonymous function -with a variable number of arguments -(see §3.4.11). -As such, chunks can define local variables, -receive arguments, and return values. -Moreover, such anonymous function is compiled as in the -scope of an external local variable called _ENV (see §2.2). -The resulting function always has _ENV as its only upvalue, -even if it does not use that variable. - - -

-A chunk can be stored in a file or in a string inside the host program. -To execute a chunk, -Lua first loads it, -precompiling the chunk's code into instructions for a virtual machine, -and then Lua executes the compiled code -with an interpreter for the virtual machine. - - -

-Chunks can also be precompiled into binary form; -see program luac and function string.dump for details. -Programs in source and compiled forms are interchangeable; -Lua automatically detects the file type and acts accordingly (see load). - - - - - -

3.3.3 – Assignment

- -

-Lua allows multiple assignments. -Therefore, the syntax for assignment -defines a list of variables on the left side -and a list of expressions on the right side. -The elements in both lists are separated by commas: - -

-	stat ::= varlist ‘=’ explist
-	varlist ::= var {‘,’ var}
-	explist ::= exp {‘,’ exp}
-

-Expressions are discussed in §3.4. - - -

-Before the assignment, -the list of values is adjusted to the length of -the list of variables. -If there are more values than needed, -the excess values are thrown away. -If there are fewer values than needed, -the list is extended with as many nil's as needed. -If the list of expressions ends with a function call, -then all values returned by that call enter the list of values, -before the adjustment -(except when the call is enclosed in parentheses; see §3.4). - - -

-The assignment statement first evaluates all its expressions -and only then the assignments are performed. -Thus the code - -

-     i = 3
-     i, a[i] = i+1, 20
-

-sets a[3] to 20, without affecting a[4] -because the i in a[i] is evaluated (to 3) -before it is assigned 4. -Similarly, the line - -

-     x, y = y, x
-

-exchanges the values of x and y, -and - -

-     x, y, z = y, z, x
-

-cyclically permutes the values of x, y, and z. - - -

-An assignment to a global name x = val -is equivalent to the assignment -_ENV.x = val (see §2.2). - - -

-The meaning of assignments to table fields and -global variables (which are actually table fields, too) -can be changed via metatables (see §2.4). - - - - - -

3.3.4 – Control Structures

-The control structures -if, while, and repeat have the usual meaning and -familiar syntax: - - - - -

-	stat ::= while exp do block end
-	stat ::= repeat block until exp
-	stat ::= if exp then block {elseif exp then block} [else block] end
-

-Lua also has a for statement, in two flavors (see §3.3.5). - - -

-The condition expression of a -control structure can return any value. -Both false and nil are considered false. -All values different from nil and false are considered true -(in particular, the number 0 and the empty string are also true). - - -

-In the repeat–until loop, -the inner block does not end at the until keyword, -but only after the condition. -So, the condition can refer to local variables -declared inside the loop block. - - -

-The goto statement transfers the program control to a label. -For syntactical reasons, -labels in Lua are considered statements too: - - - -

-	stat ::= goto Name
-	stat ::= label
-	label ::= ‘::’ Name ‘::’
-
- -

-A label is visible in the entire block where it is defined, -except -inside nested blocks where a label with the same name is defined and -inside nested functions. -A goto may jump to any visible label as long as it does not -enter into the scope of a local variable. - - -

-Labels and empty statements are called void statements, -as they perform no actions. - - -

-The break statement terminates the execution of a -while, repeat, or for loop, -skipping to the next statement after the loop: - - -

-	stat ::= break
-

-A break ends the innermost enclosing loop. - - -

-The return statement is used to return values -from a function or a chunk -(which is an anonymous function). - -Functions can return more than one value, -so the syntax for the return statement is - -

-	stat ::= return [explist] [‘;’]
-
- -

-The return statement can only be written -as the last statement of a block. -If it is really necessary to return in the middle of a block, -then an explicit inner block can be used, -as in the idiom do return end, -because now return is the last statement in its (inner) block. - - - - - -

3.3.5 – For Statement

- -

- -The for statement has two forms: -one numerical and one generic. - - -

-The numerical for loop repeats a block of code while a -control variable runs through an arithmetic progression. -It has the following syntax: - -

-	stat ::= for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end
-

-The block is repeated for name starting at the value of -the first exp, until it passes the second exp by steps of the -third exp. -More precisely, a for statement like - -

-     for v = e1, e2, e3 do block end
-

-is equivalent to the code: - -

-     do
-       local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
-       if not (var and limit and step) then error() end
-       var = var - step
-       while true do
-         var = var + step
-         if (step >= 0 and var > limit) or (step < 0 and var < limit) then
-           break
-         end
-         local v = var
-         block
-       end
-     end
-
- -

-Note the following: - -

    - -
  • -All three control expressions are evaluated only once, -before the loop starts. -They must all result in numbers. -
    • - -
  • -var, limit, and step are invisible variables. -The names shown here are for explanatory purposes only. -
    • - -
  • -If the third expression (the step) is absent, -then a step of 1 is used. -
    • - -
  • -You can use break and goto to exit a for loop. -
    • - -
  • -The loop variable v is local to the loop body. -If you need its value after the loop, -assign it to another variable before exiting the loop. -
    • - -
- -

-The generic for statement works over functions, -called iterators. -On each iteration, the iterator function is called to produce a new value, -stopping when this new value is nil. -The generic for loop has the following syntax: - -

-	stat ::= for namelist in explist do block end
-	namelist ::= Name {‘,’ Name}
-

-A for statement like - -

-     for var_1, ···, var_n in explist do block end
-

-is equivalent to the code: - -

-     do
-       local f, s, var = explist
-       while true do
-         local var_1, ···, var_n = f(s, var)
-         if var_1 == nil then break end
-         var = var_1
-         block
-       end
-     end
-

-Note the following: - -

    - -
  • -explist is evaluated only once. -Its results are an iterator function, -a state, -and an initial value for the first iterator variable. -
    • - -
  • -f, s, and var are invisible variables. -The names are here for explanatory purposes only. -
    • - -
  • -You can use break to exit a for loop. -
    • - -
  • -The loop variables var_i are local to the loop; -you cannot use their values after the for ends. -If you need these values, -then assign them to other variables before breaking or exiting the loop. -
    • - -
- - - - -

3.3.6 – Function Calls as Statements

-To allow possible side-effects, -function calls can be executed as statements: - -

-	stat ::= functioncall
-

-In this case, all returned values are thrown away. -Function calls are explained in §3.4.10. - - - - - -

3.3.7 – Local Declarations

-Local variables can be declared anywhere inside a block. -The declaration can include an initial assignment: - -

-	stat ::= local namelist [‘=’ explist]
-

-If present, an initial assignment has the same semantics -of a multiple assignment (see §3.3.3). -Otherwise, all variables are initialized with nil. - - -

-A chunk is also a block (see §3.3.2), -and so local variables can be declared in a chunk outside any explicit block. - - -

-The visibility rules for local variables are explained in §3.5. - - - - - - - -

3.4 – Expressions

- -

-The basic expressions in Lua are the following: - -

-	exp ::= prefixexp
-	exp ::= nil | false | true
-	exp ::= Numeral
-	exp ::= LiteralString
-	exp ::= functiondef
-	exp ::= tableconstructor
-	exp ::= ‘...’
-	exp ::= exp binop exp
-	exp ::= unop exp
-	prefixexp ::= var | functioncall | ‘(’ exp ‘)’
-
- -

-Numerals and literal strings are explained in §3.1; -variables are explained in §3.2; -function definitions are explained in §3.4.11; -function calls are explained in §3.4.10; -table constructors are explained in §3.4.9. -Vararg expressions, -denoted by three dots ('...'), can only be used when -directly inside a vararg function; -they are explained in §3.4.11. - - -

-Binary operators comprise arithmetic operators (see §3.4.1), -bitwise operators (see §3.4.2), -relational operators (see §3.4.4), logical operators (see §3.4.5), -and the concatenation operator (see §3.4.6). -Unary operators comprise the unary minus (see §3.4.1), -the unary bitwise NOT (see §3.4.2), -the unary logical not (see §3.4.5), -and the unary length operator (see §3.4.7). - - -

-Both function calls and vararg expressions can result in multiple values. -If a function call is used as a statement (see §3.3.6), -then its return list is adjusted to zero elements, -thus discarding all returned values. -If an expression is used as the last (or the only) element -of a list of expressions, -then no adjustment is made -(unless the expression is enclosed in parentheses). -In all other contexts, -Lua adjusts the result list to one element, -either discarding all values except the first one -or adding a single nil if there are no values. - - -

-Here are some examples: - -

-     f()                -- adjusted to 0 results
-     g(f(), x)          -- f() is adjusted to 1 result
-     g(x, f())          -- g gets x plus all results from f()
-     a,b,c = f(), x     -- f() is adjusted to 1 result (c gets nil)
-     a,b = ...          -- a gets the first vararg argument, b gets
-                        -- the second (both a and b can get nil if there
-                        -- is no corresponding vararg argument)
-     
-     a,b,c = x, f()     -- f() is adjusted to 2 results
-     a,b,c = f()        -- f() is adjusted to 3 results
-     return f()         -- returns all results from f()
-     return ...         -- returns all received vararg arguments
-     return x,y,f()     -- returns x, y, and all results from f()
-     {f()}              -- creates a list with all results from f()
-     {...}              -- creates a list with all vararg arguments
-     {f(), nil}         -- f() is adjusted to 1 result
-
- -

-Any expression enclosed in parentheses always results in only one value. -Thus, -(f(x,y,z)) is always a single value, -even if f returns several values. -(The value of (f(x,y,z)) is the first value returned by f -or nil if f does not return any values.) - - - -

3.4.1 – Arithmetic Operators

-Lua supports the following arithmetic operators: - -

    -
  • +: addition
    • -
  • -: subtraction
    • -
  • *: multiplication
    • -
  • /: float division
    • -
  • //: floor division
    • -
  • %: modulo
    • -
  • ^: exponentiation
    • -
  • -: unary minus
    • -
- -

-With the exception of exponentiation and float division, -the arithmetic operators work as follows: -If both operands are integers, -the operation is performed over integers and the result is an integer. -Otherwise, if both operands are numbers -or strings that can be converted to -numbers (see §3.4.3), -then they are converted to floats, -the operation is performed following the usual rules -for floating-point arithmetic -(usually the IEEE 754 standard), -and the result is a float. - - -

-Exponentiation and float division (/) -always convert their operands to floats -and the result is always a float. -Exponentiation uses the ISO C function pow, -so that it works for non-integer exponents too. - - -

-Floor division (//) is a division -that rounds the quotient towards minus infinity, -that is, the floor of the division of its operands. - - -

-Modulo is defined as the remainder of a division -that rounds the quotient towards minus infinity (floor division). - - -

-In case of overflows in integer arithmetic, -all operations wrap around, -according to the usual rules of two-complement arithmetic. -(In other words, -they return the unique representable integer -that is equal modulo 264 to the mathematical result.) - - - -

3.4.2 – Bitwise Operators

-Lua supports the following bitwise operators: - -

    -
  • &: bitwise AND
    • -
  • |: bitwise OR
    • -
  • ~: bitwise exclusive OR
    • -
  • >>: right shift
    • -
  • <<: left shift
    • -
  • ~: unary bitwise NOT
    • -
- -

-All bitwise operations convert its operands to integers -(see §3.4.3), -operate on all bits of those integers, -and result in an integer. - - -

-Both right and left shifts fill the vacant bits with zeros. -Negative displacements shift to the other direction; -displacements with absolute values equal to or higher than -the number of bits in an integer -result in zero (as all bits are shifted out). - - - - - -

3.4.3 – Coercions and Conversions

-Lua provides some automatic conversions between some -types and representations at run time. -Bitwise operators always convert float operands to integers. -Exponentiation and float division -always convert integer operands to floats. -All other arithmetic operations applied to mixed numbers -(integers and floats) convert the integer operand to a float; -this is called the usual rule. -The C API also converts both integers to floats and -floats to integers, as needed. -Moreover, string concatenation accepts numbers as arguments, -besides strings. - - -

-Lua also converts strings to numbers, -whenever a number is expected. - - -

-In a conversion from integer to float, -if the integer value has an exact representation as a float, -that is the result. -Otherwise, -the conversion gets the nearest higher or -the nearest lower representable value. -This kind of conversion never fails. - - -

-The conversion from float to integer -checks whether the float has an exact representation as an integer -(that is, the float has an integral value and -it is in the range of integer representation). -If it does, that representation is the result. -Otherwise, the conversion fails. - - -

-The conversion from strings to numbers goes as follows: -First, the string is converted to an integer or a float, -following its syntax and the rules of the Lua lexer. -(The string may have also leading and trailing spaces and a sign.) -Then, the resulting number (float or integer) -is converted to the type (float or integer) required by the context -(e.g., the operation that forced the conversion). - - -

-All conversions from strings to numbers -accept both a dot and the current locale mark -as the radix character. -(The Lua lexer, however, accepts only a dot.) - - -

-The conversion from numbers to strings uses a -non-specified human-readable format. -For complete control over how numbers are converted to strings, -use the format function from the string library -(see string.format). - - - - - -

3.4.4 – Relational Operators

-Lua supports the following relational operators: - -

    -
  • ==: equality
    • -
  • ~=: inequality
    • -
  • <: less than
    • -
  • >: greater than
    • -
  • <=: less or equal
    • -
  • >=: greater or equal
    • -

-These operators always result in false or true. - - -

-Equality (==) first compares the type of its operands. -If the types are different, then the result is false. -Otherwise, the values of the operands are compared. -Strings are compared in the obvious way. -Numbers are equal if they denote the same mathematical value. - - -

-Tables, userdata, and threads -are compared by reference: -two objects are considered equal only if they are the same object. -Every time you create a new object -(a table, userdata, or thread), -this new object is different from any previously existing object. -A closure is always equal to itself. -Closures with any detectable difference -(different behavior, different definition) are always different. -Closures created at different times but with no detectable differences -may be classified as equal or not -(depending on internal caching details). - - -

-You can change the way that Lua compares tables and userdata -by using the "eq" metamethod (see §2.4). - - -

-Equality comparisons do not convert strings to numbers -or vice versa. -Thus, "0"==0 evaluates to false, -and t[0] and t["0"] denote different -entries in a table. - - -

-The operator ~= is exactly the negation of equality (==). - - -

-The order operators work as follows. -If both arguments are numbers, -then they are compared according to their mathematical values -(regardless of their subtypes). -Otherwise, if both arguments are strings, -then their values are compared according to the current locale. -Otherwise, Lua tries to call the "lt" or the "le" -metamethod (see §2.4). -A comparison a > b is translated to b < a -and a >= b is translated to b <= a. - - -

-Following the IEEE 754 standard, -NaN is considered neither smaller than, -nor equal to, nor greater than any value (including itself). - - - - - -

3.4.5 – Logical Operators

-The logical operators in Lua are -and, or, and not. -Like the control structures (see §3.3.4), -all logical operators consider both false and nil as false -and anything else as true. - - -

-The negation operator not always returns false or true. -The conjunction operator and returns its first argument -if this value is false or nil; -otherwise, and returns its second argument. -The disjunction operator or returns its first argument -if this value is different from nil and false; -otherwise, or returns its second argument. -Both and and or use short-circuit evaluation; -that is, -the second operand is evaluated only if necessary. -Here are some examples: - -

-     10 or 20            --> 10
-     10 or error()       --> 10
-     nil or "a"          --> "a"
-     nil and 10          --> nil
-     false and error()   --> false
-     false and nil       --> false
-     false or nil        --> nil
-     10 and 20           --> 20
-

-(In this manual, ---> indicates the result of the preceding expression.) - - - - - -

3.4.6 – Concatenation

-The string concatenation operator in Lua is -denoted by two dots ('..'). -If both operands are strings or numbers, then they are converted to -strings according to the rules described in §3.4.3. -Otherwise, the __concat metamethod is called (see §2.4). - - - - - -

3.4.7 – The Length Operator

- -

-The length operator is denoted by the unary prefix operator #. - - -

-The length of a string is its number of bytes -(that is, the usual meaning of string length when each -character is one byte). - - -

-The length operator applied on a table -returns a border in that table. -A border in a table t is any natural number -that satisfies the following condition: - -

-     (border == 0 or t[border] ~= nil) and t[border + 1] == nil
-

-In words, -a border is any (natural) index in a table -where a non-nil value is followed by a nil value -(or zero, when index 1 is nil). - - -

-A table with exactly one border is called a sequence. -For instance, the table {10, 20, 30, 40, 50} is a sequence, -as it has only one border (5). -The table {10, 20, 30, nil, 50} has two borders (3 and 5), -and therefore it is not a sequence. -The table {nil, 20, 30, nil, nil, 60, nil} -has three borders (0, 3, and 6), -so it is not a sequence, too. -The table {} is a sequence with border 0. -Note that non-natural keys do not interfere -with whether a table is a sequence. - - -

-When t is a sequence, -#t returns its only border, -which corresponds to the intuitive notion of the length of the sequence. -When t is not a sequence, -#t can return any of its borders. -(The exact one depends on details of -the internal representation of the table, -which in turn can depend on how the table was populated and -the memory addresses of its non-numeric keys.) - - -

-The computation of the length of a table -has a guaranteed worst time of O(log n), -where n is the largest natural key in the table. - - -

-A program can modify the behavior of the length operator for -any value but strings through the __len metamethod (see §2.4). - - - - - -

3.4.8 – Precedence

-Operator precedence in Lua follows the table below, -from lower to higher priority: - -

-     or
-     and
-     <     >     <=    >=    ~=    ==
-     |
-     ~
-     &
-     <<    >>
-     ..
-     +     -
-     *     /     //    %
-     unary operators (not   #     -     ~)
-     ^
-

-As usual, -you can use parentheses to change the precedences of an expression. -The concatenation ('..') and exponentiation ('^') -operators are right associative. -All other binary operators are left associative. - - - - - -

3.4.9 – Table Constructors

-Table constructors are expressions that create tables. -Every time a constructor is evaluated, a new table is created. -A constructor can be used to create an empty table -or to create a table and initialize some of its fields. -The general syntax for constructors is - -

-	tableconstructor ::= ‘{’ [fieldlist] ‘}’
-	fieldlist ::= field {fieldsep field} [fieldsep]
-	field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp
-	fieldsep ::= ‘,’ | ‘;’
-
- -

-Each field of the form [exp1] = exp2 adds to the new table an entry -with key exp1 and value exp2. -A field of the form name = exp is equivalent to -["name"] = exp. -Finally, fields of the form exp are equivalent to -[i] = exp, where i are consecutive integers -starting with 1. -Fields in the other formats do not affect this counting. -For example, - -

-     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
-

-is equivalent to - -

-     do
-       local t = {}
-       t[f(1)] = g
-       t[1] = "x"         -- 1st exp
-       t[2] = "y"         -- 2nd exp
-       t.x = 1            -- t["x"] = 1
-       t[3] = f(x)        -- 3rd exp
-       t[30] = 23
-       t[4] = 45          -- 4th exp
-       a = t
-     end
-
- -

-The order of the assignments in a constructor is undefined. -(This order would be relevant only when there are repeated keys.) - - -

-If the last field in the list has the form exp -and the expression is a function call or a vararg expression, -then all values returned by this expression enter the list consecutively -(see §3.4.10). - - -

-The field list can have an optional trailing separator, -as a convenience for machine-generated code. - - - - - -

3.4.10 – Function Calls

-A function call in Lua has the following syntax: - -

-	functioncall ::= prefixexp args
-

-In a function call, -first prefixexp and args are evaluated. -If the value of prefixexp has type function, -then this function is called -with the given arguments. -Otherwise, the prefixexp "call" metamethod is called, -having as first argument the value of prefixexp, -followed by the original call arguments -(see §2.4). - - -

-The form - -

-	functioncall ::= prefixexp ‘:’ Name args
-

-can be used to call "methods". -A call v:name(args) -is syntactic sugar for v.name(v,args), -except that v is evaluated only once. - - -

-Arguments have the following syntax: - -

-	args ::= ‘(’ [explist] ‘)’
-	args ::= tableconstructor
-	args ::= LiteralString
-

-All argument expressions are evaluated before the call. -A call of the form f{fields} is -syntactic sugar for f({fields}); -that is, the argument list is a single new table. -A call of the form f'string' -(or f"string" or f[[string]]) -is syntactic sugar for f('string'); -that is, the argument list is a single literal string. - - -

-A call of the form return functioncall is called -a tail call. -Lua implements proper tail calls -(or proper tail recursion): -in a tail call, -the called function reuses the stack entry of the calling function. -Therefore, there is no limit on the number of nested tail calls that -a program can execute. -However, a tail call erases any debug information about the -calling function. -Note that a tail call only happens with a particular syntax, -where the return has one single function call as argument; -this syntax makes the calling function return exactly -the returns of the called function. -So, none of the following examples are tail calls: - -

-     return (f(x))        -- results adjusted to 1
-     return 2 * f(x)
-     return x, f(x)       -- additional results
-     f(x); return         -- results discarded
-     return x or f(x)     -- results adjusted to 1
-
- - - - -

3.4.11 – Function Definitions

- -

-The syntax for function definition is - -

-	functiondef ::= function funcbody
-	funcbody ::= ‘(’ [parlist] ‘)’ block end
-
- -

-The following syntactic sugar simplifies function definitions: - -

-	stat ::= function funcname funcbody
-	stat ::= local function Name funcbody
-	funcname ::= Name {‘.’ Name} [‘:’ Name]
-

-The statement - -

-     function f () body end
-

-translates to - -

-     f = function () body end
-

-The statement - -

-     function t.a.b.c.f () body end
-

-translates to - -

-     t.a.b.c.f = function () body end
-

-The statement - -

-     local function f () body end
-

-translates to - -

-     local f; f = function () body end
-

-not to - -

-     local f = function () body end
-

-(This only makes a difference when the body of the function -contains references to f.) - - -

-A function definition is an executable expression, -whose value has type function. -When Lua precompiles a chunk, -all its function bodies are precompiled too. -Then, whenever Lua executes the function definition, -the function is instantiated (or closed). -This function instance (or closure) -is the final value of the expression. - - -

-Parameters act as local variables that are -initialized with the argument values: - -

-	parlist ::= namelist [‘,’ ‘...’] | ‘...’
-

-When a function is called, -the list of arguments is adjusted to -the length of the list of parameters, -unless the function is a vararg function, -which is indicated by three dots ('...') -at the end of its parameter list. -A vararg function does not adjust its argument list; -instead, it collects all extra arguments and supplies them -to the function through a vararg expression, -which is also written as three dots. -The value of this expression is a list of all actual extra arguments, -similar to a function with multiple results. -If a vararg expression is used inside another expression -or in the middle of a list of expressions, -then its return list is adjusted to one element. -If the expression is used as the last element of a list of expressions, -then no adjustment is made -(unless that last expression is enclosed in parentheses). - - -

-As an example, consider the following definitions: - -

-     function f(a, b) end
-     function g(a, b, ...) end
-     function r() return 1,2,3 end
-

-Then, we have the following mapping from arguments to parameters and -to the vararg expression: - -

-     CALL            PARAMETERS
-     
-     f(3)             a=3, b=nil
-     f(3, 4)          a=3, b=4
-     f(3, 4, 5)       a=3, b=4
-     f(r(), 10)       a=1, b=10
-     f(r())           a=1, b=2
-     
-     g(3)             a=3, b=nil, ... -->  (nothing)
-     g(3, 4)          a=3, b=4,   ... -->  (nothing)
-     g(3, 4, 5, 8)    a=3, b=4,   ... -->  5  8
-     g(5, r())        a=5, b=1,   ... -->  2  3
-
- -

-Results are returned using the return statement (see §3.3.4). -If control reaches the end of a function -without encountering a return statement, -then the function returns with no results. - - -

- -There is a system-dependent limit on the number of values -that a function may return. -This limit is guaranteed to be larger than 1000. - - -

-The colon syntax -is used for defining methods, -that is, functions that have an implicit extra parameter self. -Thus, the statement - -

-     function t.a.b.c:f (params) body end
-

-is syntactic sugar for - -

-     t.a.b.c.f = function (self, params) body end
-
- - - - - - -

3.5 – Visibility Rules

- -

- -Lua is a lexically scoped language. -The scope of a local variable begins at the first statement after -its declaration and lasts until the last non-void statement -of the innermost block that includes the declaration. -Consider the following example: - -

-     x = 10                -- global variable
-     do                    -- new block
-       local x = x         -- new 'x', with value 10
-       print(x)            --> 10
-       x = x+1
-       do                  -- another block
-         local x = x+1     -- another 'x'
-         print(x)          --> 12
-       end
-       print(x)            --> 11
-     end
-     print(x)              --> 10  (the global one)
-
- -

-Notice that, in a declaration like local x = x, -the new x being declared is not in scope yet, -and so the second x refers to the outside variable. - - -

-Because of the lexical scoping rules, -local variables can be freely accessed by functions -defined inside their scope. -A local variable used by an inner function is called -an upvalue, or external local variable, -inside the inner function. - - -

-Notice that each execution of a local statement -defines new local variables. -Consider the following example: - -

-     a = {}
-     local x = 20
-     for i=1,10 do
-       local y = 0
-       a[i] = function () y=y+1; return x+y end
-     end
-

-The loop creates ten closures -(that is, ten instances of the anonymous function). -Each of these closures uses a different y variable, -while all of them share the same x. - - - - - -

4 – The Application Program Interface

- -

- -This section describes the C API for Lua, that is, -the set of C functions available to the host program to communicate -with Lua. -All API functions and related types and constants -are declared in the header file lua.h. - - -

-Even when we use the term "function", -any facility in the API may be provided as a macro instead. -Except where stated otherwise, -all such macros use each of their arguments exactly once -(except for the first argument, which is always a Lua state), -and so do not generate any hidden side-effects. - - -

-As in most C libraries, -the Lua API functions do not check their arguments for validity or consistency. -However, you can change this behavior by compiling Lua -with the macro LUA_USE_APICHECK defined. - - -

-The Lua library is fully reentrant: -it has no global variables. -It keeps all information it needs in a dynamic structure, -called the Lua state. - - -

-Each Lua state has one or more threads, -which correspond to independent, cooperative lines of execution. -The type lua_State (despite its name) refers to a thread. -(Indirectly, through the thread, it also refers to the -Lua state associated to the thread.) - - -

-A pointer to a thread must be passed as the first argument to -every function in the library, except to lua_newstate, -which creates a Lua state from scratch and returns a pointer -to the main thread in the new state. - - - -

4.1 – The Stack

- -

-Lua uses a virtual stack to pass values to and from C. -Each element in this stack represents a Lua value -(nil, number, string, etc.). -Functions in the API can access this stack through the -Lua state parameter that they receive. - - -

-Whenever Lua calls C, the called function gets a new stack, -which is independent of previous stacks and of stacks of -C functions that are still active. -This stack initially contains any arguments to the C function -and it is where the C function can store temporary -Lua values and must push its results -to be returned to the caller (see lua_CFunction). - - -

-For convenience, -most query operations in the API do not follow a strict stack discipline. -Instead, they can refer to any element in the stack -by using an index: -A positive index represents an absolute stack position -(starting at 1); -a negative index represents an offset relative to the top of the stack. -More specifically, if the stack has n elements, -then index 1 represents the first element -(that is, the element that was pushed onto the stack first) -and -index n represents the last element; -index -1 also represents the last element -(that is, the element at the top) -and index -n represents the first element. - - - - - -

4.2 – Stack Size

- -

-When you interact with the Lua API, -you are responsible for ensuring consistency. -In particular, -you are responsible for controlling stack overflow. -You can use the function lua_checkstack -to ensure that the stack has enough space for pushing new elements. - - -

-Whenever Lua calls C, -it ensures that the stack has space for -at least LUA_MINSTACK extra slots. -LUA_MINSTACK is defined as 20, -so that usually you do not have to worry about stack space -unless your code has loops pushing elements onto the stack. - - -

-When you call a Lua function -without a fixed number of results (see lua_call), -Lua ensures that the stack has enough space for all results, -but it does not ensure any extra space. -So, before pushing anything in the stack after such a call -you should use lua_checkstack. - - - - - -

4.3 – Valid and Acceptable Indices

- -

-Any function in the API that receives stack indices -works only with valid indices or acceptable indices. - - -

-A valid index is an index that refers to a -position that stores a modifiable Lua value. -It comprises stack indices between 1 and the stack top -(1 ≤ abs(index) ≤ top) - -plus pseudo-indices, -which represent some positions that are accessible to C code -but that are not in the stack. -Pseudo-indices are used to access the registry (see §4.5) -and the upvalues of a C function (see §4.4). - - -

-Functions that do not need a specific mutable position, -but only a value (e.g., query functions), -can be called with acceptable indices. -An acceptable index can be any valid index, -but it also can be any positive index after the stack top -within the space allocated for the stack, -that is, indices up to the stack size. -(Note that 0 is never an acceptable index.) -Except when noted otherwise, -functions in the API work with acceptable indices. - - -

-Acceptable indices serve to avoid extra tests -against the stack top when querying the stack. -For instance, a C function can query its third argument -without the need to first check whether there is a third argument, -that is, without the need to check whether 3 is a valid index. - - -

-For functions that can be called with acceptable indices, -any non-valid index is treated as if it -contains a value of a virtual type LUA_TNONE, -which behaves like a nil value. - - - - - -

4.4 – C Closures

- -

-When a C function is created, -it is possible to associate some values with it, -thus creating a C closure -(see lua_pushcclosure); -these values are called upvalues and are -accessible to the function whenever it is called. - - -

-Whenever a C function is called, -its upvalues are located at specific pseudo-indices. -These pseudo-indices are produced by the macro -lua_upvalueindex. -The first upvalue associated with a function is at index -lua_upvalueindex(1), and so on. -Any access to lua_upvalueindex(n), -where n is greater than the number of upvalues of the -current function -(but not greater than 256, -which is one plus the maximum number of upvalues in a closure), -produces an acceptable but invalid index. - - - - - -

4.5 – Registry

- -

-Lua provides a registry, -a predefined table that can be used by any C code to -store whatever Lua values it needs to store. -The registry table is always located at pseudo-index -LUA_REGISTRYINDEX. -Any C library can store data into this table, -but it must take care to choose keys -that are different from those used -by other libraries, to avoid collisions. -Typically, you should use as key a string containing your library name, -or a light userdata with the address of a C object in your code, -or any Lua object created by your code. -As with variable names, -string keys starting with an underscore followed by -uppercase letters are reserved for Lua. - - -

-The integer keys in the registry are used -by the reference mechanism (see luaL_ref) -and by some predefined values. -Therefore, integer keys must not be used for other purposes. - - -

-When you create a new Lua state, -its registry comes with some predefined values. -These predefined values are indexed with integer keys -defined as constants in lua.h. -The following constants are defined: - -

    -
  • LUA_RIDX_MAINTHREAD: At this index the registry has -the main thread of the state. -(The main thread is the one created together with the state.) -
    • - -
  • LUA_RIDX_GLOBALS: At this index the registry has -the global environment. -
    • -
- - - - -

4.6 – Error Handling in C

- -

-Internally, Lua uses the C longjmp facility to handle errors. -(Lua will use exceptions if you compile it as C++; -search for LUAI_THROW in the source code for details.) -When Lua faces any error -(such as a memory allocation error or a type error) -it raises an error; -that is, it does a long jump. -A protected environment uses setjmp -to set a recovery point; -any error jumps to the most recent active recovery point. - - -

-Inside a C function you can raise an error by calling lua_error. - - -

-Most functions in the API can raise an error, -for instance due to a memory allocation error. -The documentation for each function indicates whether -it can raise errors. - - -

-If an error happens outside any protected environment, -Lua calls a panic function (see lua_atpanic) -and then calls abort, -thus exiting the host application. -Your panic function can avoid this exit by -never returning -(e.g., doing a long jump to your own recovery point outside Lua). - - -

-The panic function, -as its name implies, -is a mechanism of last resort. -Programs should avoid it. -As a general rule, -when a C function is called by Lua with a Lua state, -it can do whatever it wants on that Lua state, -as it should be already protected. -However, -when C code operates on other Lua states -(e.g., a Lua argument to the function, -a Lua state stored in the registry, or -the result of lua_newthread), -it should use them only in API calls that cannot raise errors. - - -

-The panic function runs as if it were a message handler (see §2.3); -in particular, the error object is at the top of the stack. -However, there is no guarantee about stack space. -To push anything on the stack, -the panic function must first check the available space (see §4.2). - - - - - -

4.7 – Handling Yields in C

- -

-Internally, Lua uses the C longjmp facility to yield a coroutine. -Therefore, if a C function foo calls an API function -and this API function yields -(directly or indirectly by calling another function that yields), -Lua cannot return to foo any more, -because the longjmp removes its frame from the C stack. - - -

-To avoid this kind of problem, -Lua raises an error whenever it tries to yield across an API call, -except for three functions: -lua_yieldk, lua_callk, and lua_pcallk. -All those functions receive a continuation function -(as a parameter named k) to continue execution after a yield. - - -

-We need to set some terminology to explain continuations. -We have a C function called from Lua which we will call -the original function. -This original function then calls one of those three functions in the C API, -which we will call the callee function, -that then yields the current thread. -(This can happen when the callee function is lua_yieldk, -or when the callee function is either lua_callk or lua_pcallk -and the function called by them yields.) - - -

-Suppose the running thread yields while executing the callee function. -After the thread resumes, -it eventually will finish running the callee function. -However, -the callee function cannot return to the original function, -because its frame in the C stack was destroyed by the yield. -Instead, Lua calls a continuation function, -which was given as an argument to the callee function. -As the name implies, -the continuation function should continue the task -of the original function. - - -

-As an illustration, consider the following function: - -

-     int original_function (lua_State *L) {
-       ...     /* code 1 */
-       status = lua_pcall(L, n, m, h);  /* calls Lua */
-       ...     /* code 2 */
-     }
-

-Now we want to allow -the Lua code being run by lua_pcall to yield. -First, we can rewrite our function like here: - -

-     int k (lua_State *L, int status, lua_KContext ctx) {
-       ...  /* code 2 */
-     }
-     
-     int original_function (lua_State *L) {
-       ...     /* code 1 */
-       return k(L, lua_pcall(L, n, m, h), ctx);
-     }
-

-In the above code, -the new function k is a -continuation function (with type lua_KFunction), -which should do all the work that the original function -was doing after calling lua_pcall. -Now, we must inform Lua that it must call k if the Lua code -being executed by lua_pcall gets interrupted in some way -(errors or yielding), -so we rewrite the code as here, -replacing lua_pcall by lua_pcallk: - -

-     int original_function (lua_State *L) {
-       ...     /* code 1 */
-       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
-     }
-

-Note the external, explicit call to the continuation: -Lua will call the continuation only if needed, that is, -in case of errors or resuming after a yield. -If the called function returns normally without ever yielding, -lua_pcallk (and lua_callk) will also return normally. -(Of course, instead of calling the continuation in that case, -you can do the equivalent work directly inside the original function.) - - -

-Besides the Lua state, -the continuation function has two other parameters: -the final status of the call plus the context value (ctx) that -was passed originally to lua_pcallk. -(Lua does not use this context value; -it only passes this value from the original function to the -continuation function.) -For lua_pcallk, -the status is the same value that would be returned by lua_pcallk, -except that it is LUA_YIELD when being executed after a yield -(instead of LUA_OK). -For lua_yieldk and lua_callk, -the status is always LUA_YIELD when Lua calls the continuation. -(For these two functions, -Lua will not call the continuation in case of errors, -because they do not handle errors.) -Similarly, when using lua_callk, -you should call the continuation function -with LUA_OK as the status. -(For lua_yieldk, there is not much point in calling -directly the continuation function, -because lua_yieldk usually does not return.) - - -

-Lua treats the continuation function as if it were the original function. -The continuation function receives the same Lua stack -from the original function, -in the same state it would be if the callee function had returned. -(For instance, -after a lua_callk the function and its arguments are -removed from the stack and replaced by the results from the call.) -It also has the same upvalues. -Whatever it returns is handled by Lua as if it were the return -of the original function. - - - - - -

4.8 – Functions and Types

- -

-Here we list all functions and types from the C API in -alphabetical order. -Each function has an indicator like this: -[-o, +p, x] - - -

-The first field, o, -is how many elements the function pops from the stack. -The second field, p, -is how many elements the function pushes onto the stack. -(Any function always pushes its results after popping its arguments.) -A field in the form x|y means the function can push (or pop) -x or y elements, -depending on the situation; -an interrogation mark '?' means that -we cannot know how many elements the function pops/pushes -by looking only at its arguments -(e.g., they may depend on what is on the stack). -The third field, x, -tells whether the function may raise errors: -'-' means the function never raises any error; -'m' means the function may raise out-of-memory errors -and errors running a __gc metamethod; -'e' means the function may raise any errors -(it can run arbitrary Lua code, -either directly or through metamethods); -'v' means the function may raise an error on purpose. - - - -

lua_absindex

-[-0, +0, –] -

int lua_absindex (lua_State *L, int idx);
- -

-Converts the acceptable index idx -into an equivalent absolute index -(that is, one that does not depend on the stack top). - - - - - -

lua_Alloc

-
typedef void * (*lua_Alloc) (void *ud,
-                             void *ptr,
-                             size_t osize,
-                             size_t nsize);
- -

-The type of the memory-allocation function used by Lua states. -The allocator function must provide a -functionality similar to realloc, -but not exactly the same. -Its arguments are -ud, an opaque pointer passed to lua_newstate; -ptr, a pointer to the block being allocated/reallocated/freed; -osize, the original size of the block or some code about what -is being allocated; -and nsize, the new size of the block. - - -

-When ptr is not NULL, -osize is the size of the block pointed by ptr, -that is, the size given when it was allocated or reallocated. - - -

-When ptr is NULL, -osize encodes the kind of object that Lua is allocating. -osize is any of -LUA_TSTRING, LUA_TTABLE, LUA_TFUNCTION, -LUA_TUSERDATA, or LUA_TTHREAD when (and only when) -Lua is creating a new object of that type. -When osize is some other value, -Lua is allocating memory for something else. - - -

-Lua assumes the following behavior from the allocator function: - - -

-When nsize is zero, -the allocator must behave like free -and return NULL. - - -

-When nsize is not zero, -the allocator must behave like realloc. -The allocator returns NULL -if and only if it cannot fulfill the request. -Lua assumes that the allocator never fails when -osize >= nsize. - - -

-Here is a simple implementation for the allocator function. -It is used in the auxiliary library by luaL_newstate. - -

-     static void *l_alloc (void *ud, void *ptr, size_t osize,
-                                                size_t nsize) {
-       (void)ud;  (void)osize;  /* not used */
-       if (nsize == 0) {
-         free(ptr);
-         return NULL;
-       }
-       else
-         return realloc(ptr, nsize);
-     }
-

-Note that Standard C ensures -that free(NULL) has no effect and that -realloc(NULL,size) is equivalent to malloc(size). -This code assumes that realloc does not fail when shrinking a block. -(Although Standard C does not ensure this behavior, -it seems to be a safe assumption.) - - - - - -

lua_arith

-[-(2|1), +1, e] -

void lua_arith (lua_State *L, int op);
- -

-Performs an arithmetic or bitwise operation over the two values -(or one, in the case of negations) -at the top of the stack, -with the value at the top being the second operand, -pops these values, and pushes the result of the operation. -The function follows the semantics of the corresponding Lua operator -(that is, it may call metamethods). - - -

-The value of op must be one of the following constants: - -

- - - - -

lua_atpanic

-[-0, +0, –] -

lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
- -

-Sets a new panic function and returns the old one (see §4.6). - - - - - -

lua_call

-[-(nargs+1), +nresults, e] -

void lua_call (lua_State *L, int nargs, int nresults);
- -

-Calls a function. - - -

-To call a function you must use the following protocol: -first, the function to be called is pushed onto the stack; -then, the arguments to the function are pushed -in direct order; -that is, the first argument is pushed first. -Finally you call lua_call; -nargs is the number of arguments that you pushed onto the stack. -All arguments and the function value are popped from the stack -when the function is called. -The function results are pushed onto the stack when the function returns. -The number of results is adjusted to nresults, -unless nresults is LUA_MULTRET. -In this case, all results from the function are pushed; -Lua takes care that the returned values fit into the stack space, -but it does not ensure any extra space in the stack. -The function results are pushed onto the stack in direct order -(the first result is pushed first), -so that after the call the last result is on the top of the stack. - - -

-Any error inside the called function is propagated upwards -(with a longjmp). - - -

-The following example shows how the host program can do the -equivalent to this Lua code: - -

-     a = f("how", t.x, 14)
-

-Here it is in C: - -

-     lua_getglobal(L, "f");                  /* function to be called */
-     lua_pushliteral(L, "how");                       /* 1st argument */
-     lua_getglobal(L, "t");                    /* table to be indexed */
-     lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
-     lua_remove(L, -2);                  /* remove 't' from the stack */
-     lua_pushinteger(L, 14);                          /* 3rd argument */
-     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
-     lua_setglobal(L, "a");                         /* set global 'a' */
-

-Note that the code above is balanced: -at its end, the stack is back to its original configuration. -This is considered good programming practice. - - - - - -

lua_callk

-[-(nargs + 1), +nresults, e] -

void lua_callk (lua_State *L,
-                int nargs,
-                int nresults,
-                lua_KContext ctx,
-                lua_KFunction k);
- -

-This function behaves exactly like lua_call, -but allows the called function to yield (see §4.7). - - - - - -

lua_CFunction

-
typedef int (*lua_CFunction) (lua_State *L);
- -

-Type for C functions. - - -

-In order to communicate properly with Lua, -a C function must use the following protocol, -which defines the way parameters and results are passed: -a C function receives its arguments from Lua in its stack -in direct order (the first argument is pushed first). -So, when the function starts, -lua_gettop(L) returns the number of arguments received by the function. -The first argument (if any) is at index 1 -and its last argument is at index lua_gettop(L). -To return values to Lua, a C function just pushes them onto the stack, -in direct order (the first result is pushed first), -and returns the number of results. -Any other value in the stack below the results will be properly -discarded by Lua. -Like a Lua function, a C function called by Lua can also return -many results. - - -

-As an example, the following function receives a variable number -of numeric arguments and returns their average and their sum: - -

-     static int foo (lua_State *L) {
-       int n = lua_gettop(L);    /* number of arguments */
-       lua_Number sum = 0.0;
-       int i;
-       for (i = 1; i <= n; i++) {
-         if (!lua_isnumber(L, i)) {
-           lua_pushliteral(L, "incorrect argument");
-           lua_error(L);
-         }
-         sum += lua_tonumber(L, i);
-       }
-       lua_pushnumber(L, sum/n);        /* first result */
-       lua_pushnumber(L, sum);         /* second result */
-       return 2;                   /* number of results */
-     }
-
- - - - -

lua_checkstack

-[-0, +0, –] -

int lua_checkstack (lua_State *L, int n);
- -

-Ensures that the stack has space for at least n extra slots -(that is, that you can safely push up to n values into it). -It returns false if it cannot fulfill the request, -either because it would cause the stack -to be larger than a fixed maximum size -(typically at least several thousand elements) or -because it cannot allocate memory for the extra space. -This function never shrinks the stack; -if the stack already has space for the extra slots, -it is left unchanged. - - - - - -

lua_close

-[-0, +0, –] -

void lua_close (lua_State *L);
- -

-Destroys all objects in the given Lua state -(calling the corresponding garbage-collection metamethods, if any) -and frees all dynamic memory used by this state. -In several platforms, you may not need to call this function, -because all resources are naturally released when the host program ends. -On the other hand, long-running programs that create multiple states, -such as daemons or web servers, -will probably need to close states as soon as they are not needed. - - - - - -

lua_compare

-[-0, +0, e] -

int lua_compare (lua_State *L, int index1, int index2, int op);
- -

-Compares two Lua values. -Returns 1 if the value at index index1 satisfies op -when compared with the value at index index2, -following the semantics of the corresponding Lua operator -(that is, it may call metamethods). -Otherwise returns 0. -Also returns 0 if any of the indices is not valid. - - -

-The value of op must be one of the following constants: - -

    - -
  • LUA_OPEQ: compares for equality (==)
    • -
  • LUA_OPLT: compares for less than (<)
    • -
  • LUA_OPLE: compares for less or equal (<=)
    • - -
- - - - -

lua_concat

-[-n, +1, e] -

void lua_concat (lua_State *L, int n);
- -

-Concatenates the n values at the top of the stack, -pops them, and leaves the result at the top. -If n is 1, the result is the single value on the stack -(that is, the function does nothing); -if n is 0, the result is the empty string. -Concatenation is performed following the usual semantics of Lua -(see §3.4.6). - - - - - -

lua_copy

-[-0, +0, –] -

void lua_copy (lua_State *L, int fromidx, int toidx);
- -

-Copies the element at index fromidx -into the valid index toidx, -replacing the value at that position. -Values at other positions are not affected. - - - - - -

lua_createtable

-[-0, +1, m] -

void lua_createtable (lua_State *L, int narr, int nrec);
- -

-Creates a new empty table and pushes it onto the stack. -Parameter narr is a hint for how many elements the table -will have as a sequence; -parameter nrec is a hint for how many other elements -the table will have. -Lua may use these hints to preallocate memory for the new table. -This preallocation is useful for performance when you know in advance -how many elements the table will have. -Otherwise you can use the function lua_newtable. - - - - - -

lua_dump

-[-0, +0, –] -

int lua_dump (lua_State *L,
-                        lua_Writer writer,
-                        void *data,
-                        int strip);
- -

-Dumps a function as a binary chunk. -Receives a Lua function on the top of the stack -and produces a binary chunk that, -if loaded again, -results in a function equivalent to the one dumped. -As it produces parts of the chunk, -lua_dump calls function writer (see lua_Writer) -with the given data -to write them. - - -

-If strip is true, -the binary representation may not include all debug information -about the function, -to save space. - - -

-The value returned is the error code returned by the last -call to the writer; -0 means no errors. - - -

-This function does not pop the Lua function from the stack. - - - - - -

lua_error

-[-1, +0, v] -

int lua_error (lua_State *L);
- -

-Generates a Lua error, -using the value at the top of the stack as the error object. -This function does a long jump, -and therefore never returns -(see luaL_error). - - - - - -

lua_gc

-[-0, +0, m] -

int lua_gc (lua_State *L, int what, int data);
- -

-Controls the garbage collector. - - -

-This function performs several tasks, -according to the value of the parameter what: - -

    - -
  • LUA_GCSTOP: -stops the garbage collector. -
    • - -
  • LUA_GCRESTART: -restarts the garbage collector. -
    • - -
  • LUA_GCCOLLECT: -performs a full garbage-collection cycle. -
    • - -
  • LUA_GCCOUNT: -returns the current amount of memory (in Kbytes) in use by Lua. -
    • - -
  • LUA_GCCOUNTB: -returns the remainder of dividing the current amount of bytes of -memory in use by Lua by 1024. -
    • - -
  • LUA_GCSTEP: -performs an incremental step of garbage collection. -
    • - -
  • LUA_GCSETPAUSE: -sets data as the new value -for the pause of the collector (see §2.5) -and returns the previous value of the pause. -
    • - -
  • LUA_GCSETSTEPMUL: -sets data as the new value for the step multiplier of -the collector (see §2.5) -and returns the previous value of the step multiplier. -
    • - -
  • LUA_GCISRUNNING: -returns a boolean that tells whether the collector is running -(i.e., not stopped). -
    • - -
- -

-For more details about these options, -see collectgarbage. - - - - - -

lua_getallocf

-[-0, +0, –] -

lua_Alloc lua_getallocf (lua_State *L, void **ud);
- -

-Returns the memory-allocation function of a given state. -If ud is not NULL, Lua stores in *ud the -opaque pointer given when the memory-allocator function was set. - - - - - -

lua_getfield

-[-0, +1, e] -

int lua_getfield (lua_State *L, int index, const char *k);
- -

-Pushes onto the stack the value t[k], -where t is the value at the given index. -As in Lua, this function may trigger a metamethod -for the "index" event (see §2.4). - - -

-Returns the type of the pushed value. - - - - - -

lua_getextraspace

-[-0, +0, –] -

void *lua_getextraspace (lua_State *L);
- -

-Returns a pointer to a raw memory area associated with the -given Lua state. -The application can use this area for any purpose; -Lua does not use it for anything. - - -

-Each new thread has this area initialized with a copy -of the area of the main thread. - - -

-By default, this area has the size of a pointer to void, -but you can recompile Lua with a different size for this area. -(See LUA_EXTRASPACE in luaconf.h.) - - - - - -

lua_getglobal

-[-0, +1, e] -

int lua_getglobal (lua_State *L, const char *name);
- -

-Pushes onto the stack the value of the global name. -Returns the type of that value. - - - - - -

lua_geti

-[-0, +1, e] -

int lua_geti (lua_State *L, int index, lua_Integer i);
- -

-Pushes onto the stack the value t[i], -where t is the value at the given index. -As in Lua, this function may trigger a metamethod -for the "index" event (see §2.4). - - -

-Returns the type of the pushed value. - - - - - -

lua_getmetatable

-[-0, +(0|1), –] -

int lua_getmetatable (lua_State *L, int index);
- -

-If the value at the given index has a metatable, -the function pushes that metatable onto the stack and returns 1. -Otherwise, -the function returns 0 and pushes nothing on the stack. - - - - - -

lua_gettable

-[-1, +1, e] -

int lua_gettable (lua_State *L, int index);
- -

-Pushes onto the stack the value t[k], -where t is the value at the given index -and k is the value at the top of the stack. - - -

-This function pops the key from the stack, -pushing the resulting value in its place. -As in Lua, this function may trigger a metamethod -for the "index" event (see §2.4). - - -

-Returns the type of the pushed value. - - - - - -

lua_gettop

-[-0, +0, –] -

int lua_gettop (lua_State *L);
- -

-Returns the index of the top element in the stack. -Because indices start at 1, -this result is equal to the number of elements in the stack; -in particular, 0 means an empty stack. - - - - - -

lua_getuservalue

-[-0, +1, –] -

int lua_getuservalue (lua_State *L, int index);
- -

-Pushes onto the stack the Lua value associated with the full userdata -at the given index. - - -

-Returns the type of the pushed value. - - - - - -

lua_insert

-[-1, +1, –] -

void lua_insert (lua_State *L, int index);
- -

-Moves the top element into the given valid index, -shifting up the elements above this index to open space. -This function cannot be called with a pseudo-index, -because a pseudo-index is not an actual stack position. - - - - - -

lua_Integer

-
typedef ... lua_Integer;
- -

-The type of integers in Lua. - - -

-By default this type is long long, -(usually a 64-bit two-complement integer), -but that can be changed to long or int -(usually a 32-bit two-complement integer). -(See LUA_INT_TYPE in luaconf.h.) - - -

-Lua also defines the constants -LUA_MININTEGER and LUA_MAXINTEGER, -with the minimum and the maximum values that fit in this type. - - - - - -

lua_isboolean

-[-0, +0, –] -

int lua_isboolean (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a boolean, -and 0 otherwise. - - - - - -

lua_iscfunction

-[-0, +0, –] -

int lua_iscfunction (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a C function, -and 0 otherwise. - - - - - -

lua_isfunction

-[-0, +0, –] -

int lua_isfunction (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a function -(either C or Lua), and 0 otherwise. - - - - - -

lua_isinteger

-[-0, +0, –] -

int lua_isinteger (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is an integer -(that is, the value is a number and is represented as an integer), -and 0 otherwise. - - - - - -

lua_islightuserdata

-[-0, +0, –] -

int lua_islightuserdata (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a light userdata, -and 0 otherwise. - - - - - -

lua_isnil

-[-0, +0, –] -

int lua_isnil (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is nil, -and 0 otherwise. - - - - - -

lua_isnone

-[-0, +0, –] -

int lua_isnone (lua_State *L, int index);
- -

-Returns 1 if the given index is not valid, -and 0 otherwise. - - - - - -

lua_isnoneornil

-[-0, +0, –] -

int lua_isnoneornil (lua_State *L, int index);
- -

-Returns 1 if the given index is not valid -or if the value at this index is nil, -and 0 otherwise. - - - - - -

lua_isnumber

-[-0, +0, –] -

int lua_isnumber (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a number -or a string convertible to a number, -and 0 otherwise. - - - - - -

lua_isstring

-[-0, +0, –] -

int lua_isstring (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a string -or a number (which is always convertible to a string), -and 0 otherwise. - - - - - -

lua_istable

-[-0, +0, –] -

int lua_istable (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a table, -and 0 otherwise. - - - - - -

lua_isthread

-[-0, +0, –] -

int lua_isthread (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a thread, -and 0 otherwise. - - - - - -

lua_isuserdata

-[-0, +0, –] -

int lua_isuserdata (lua_State *L, int index);
- -

-Returns 1 if the value at the given index is a userdata -(either full or light), and 0 otherwise. - - - - - -

lua_isyieldable

-[-0, +0, –] -

int lua_isyieldable (lua_State *L);
- -

-Returns 1 if the given coroutine can yield, -and 0 otherwise. - - - - - -

lua_KContext

-
typedef ... lua_KContext;
- -

-The type for continuation-function contexts. -It must be a numeric type. -This type is defined as intptr_t -when intptr_t is available, -so that it can store pointers too. -Otherwise, it is defined as ptrdiff_t. - - - - - -

lua_KFunction

-
typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);
- -

-Type for continuation functions (see §4.7). - - - - - -

lua_len

-[-0, +1, e] -

void lua_len (lua_State *L, int index);
- -

-Returns the length of the value at the given index. -It is equivalent to the '#' operator in Lua (see §3.4.7) and -may trigger a metamethod for the "length" event (see §2.4). -The result is pushed on the stack. - - - - - -

lua_load

-[-0, +1, –] -

int lua_load (lua_State *L,
-              lua_Reader reader,
-              void *data,
-              const char *chunkname,
-              const char *mode);
- -

-Loads a Lua chunk without running it. -If there are no errors, -lua_load pushes the compiled chunk as a Lua -function on top of the stack. -Otherwise, it pushes an error message. - - -

-The return values of lua_load are: - -

    - -
  • LUA_OK: no errors;
    • - -
  • LUA_ERRSYNTAX: -syntax error during precompilation;
    • - -
  • LUA_ERRMEM: -memory allocation (out-of-memory) error;
    • - -
  • LUA_ERRGCMM: -error while running a __gc metamethod. -(This error has no relation with the chunk being loaded. -It is generated by the garbage collector.) -
    • - -
- -

-The lua_load function uses a user-supplied reader function -to read the chunk (see lua_Reader). -The data argument is an opaque value passed to the reader function. - - -

-The chunkname argument gives a name to the chunk, -which is used for error messages and in debug information (see §4.9). - - -

-lua_load automatically detects whether the chunk is text or binary -and loads it accordingly (see program luac). -The string mode works as in function load, -with the addition that -a NULL value is equivalent to the string "bt". - - -

-lua_load uses the stack internally, -so the reader function must always leave the stack -unmodified when returning. - - -

-If the resulting function has upvalues, -its first upvalue is set to the value of the global environment -stored at index LUA_RIDX_GLOBALS in the registry (see §4.5). -When loading main chunks, -this upvalue will be the _ENV variable (see §2.2). -Other upvalues are initialized with nil. - - - - - -

lua_newstate

-[-0, +0, –] -

lua_State *lua_newstate (lua_Alloc f, void *ud);
- -

-Creates a new thread running in a new, independent state. -Returns NULL if it cannot create the thread or the state -(due to lack of memory). -The argument f is the allocator function; -Lua does all memory allocation for this state -through this function (see lua_Alloc). -The second argument, ud, is an opaque pointer that Lua -passes to the allocator in every call. - - - - - -

lua_newtable

-[-0, +1, m] -

void lua_newtable (lua_State *L);
- -

-Creates a new empty table and pushes it onto the stack. -It is equivalent to lua_createtable(L, 0, 0). - - - - - -

lua_newthread

-[-0, +1, m] -

lua_State *lua_newthread (lua_State *L);
- -

-Creates a new thread, pushes it on the stack, -and returns a pointer to a lua_State that represents this new thread. -The new thread returned by this function shares with the original thread -its global environment, -but has an independent execution stack. - - -

-There is no explicit function to close or to destroy a thread. -Threads are subject to garbage collection, -like any Lua object. - - - - - -

lua_newuserdata

-[-0, +1, m] -

void *lua_newuserdata (lua_State *L, size_t size);
- -

-This function allocates a new block of memory with the given size, -pushes onto the stack a new full userdata with the block address, -and returns this address. -The host program can freely use this memory. - - - - - -

lua_next

-[-1, +(2|0), e] -

int lua_next (lua_State *L, int index);
- -

-Pops a key from the stack, -and pushes a key–value pair from the table at the given index -(the "next" pair after the given key). -If there are no more elements in the table, -then lua_next returns 0 (and pushes nothing). - - -

-A typical traversal looks like this: - -

-     /* table is in the stack at index 't' */
-     lua_pushnil(L);  /* first key */
-     while (lua_next(L, t) != 0) {
-       /* uses 'key' (at index -2) and 'value' (at index -1) */
-       printf("%s - %s\n",
-              lua_typename(L, lua_type(L, -2)),
-              lua_typename(L, lua_type(L, -1)));
-       /* removes 'value'; keeps 'key' for next iteration */
-       lua_pop(L, 1);
-     }
-
- -

-While traversing a table, -do not call lua_tolstring directly on a key, -unless you know that the key is actually a string. -Recall that lua_tolstring may change -the value at the given index; -this confuses the next call to lua_next. - - -

-See function next for the caveats of modifying -the table during its traversal. - - - - - -

lua_Number

-
typedef ... lua_Number;
- -

-The type of floats in Lua. - - -

-By default this type is double, -but that can be changed to a single float or a long double. -(See LUA_FLOAT_TYPE in luaconf.h.) - - - - - -

lua_numbertointeger

-
int lua_numbertointeger (lua_Number n, lua_Integer *p);
- -

-Converts a Lua float to a Lua integer. -This macro assumes that n has an integral value. -If that value is within the range of Lua integers, -it is converted to an integer and assigned to *p. -The macro results in a boolean indicating whether the -conversion was successful. -(Note that this range test can be tricky to do -correctly without this macro, -due to roundings.) - - -

-This macro may evaluate its arguments more than once. - - - - - -

lua_pcall

-[-(nargs + 1), +(nresults|1), –] -

int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);
- -

-Calls a function in protected mode. - - -

-Both nargs and nresults have the same meaning as -in lua_call. -If there are no errors during the call, -lua_pcall behaves exactly like lua_call. -However, if there is any error, -lua_pcall catches it, -pushes a single value on the stack (the error object), -and returns an error code. -Like lua_call, -lua_pcall always removes the function -and its arguments from the stack. - - -

-If msgh is 0, -then the error object returned on the stack -is exactly the original error object. -Otherwise, msgh is the stack index of a -message handler. -(This index cannot be a pseudo-index.) -In case of runtime errors, -this function will be called with the error object -and its return value will be the object -returned on the stack by lua_pcall. - - -

-Typically, the message handler is used to add more debug -information to the error object, such as a stack traceback. -Such information cannot be gathered after the return of lua_pcall, -since by then the stack has unwound. - - -

-The lua_pcall function returns one of the following constants -(defined in lua.h): - -

    - -
  • LUA_OK (0): -success.
    • - -
  • LUA_ERRRUN: -a runtime error. -
    • - -
  • LUA_ERRMEM: -memory allocation error. -For such errors, Lua does not call the message handler. -
    • - -
  • LUA_ERRERR: -error while running the message handler. -
    • - -
  • LUA_ERRGCMM: -error while running a __gc metamethod. -For such errors, Lua does not call the message handler -(as this kind of error typically has no relation -with the function being called). -
    • - -
- - - - -

lua_pcallk

-[-(nargs + 1), +(nresults|1), –] -

int lua_pcallk (lua_State *L,
-                int nargs,
-                int nresults,
-                int msgh,
-                lua_KContext ctx,
-                lua_KFunction k);
- -

-This function behaves exactly like lua_pcall, -but allows the called function to yield (see §4.7). - - - - - -

lua_pop

-[-n, +0, –] -

void lua_pop (lua_State *L, int n);
- -

-Pops n elements from the stack. - - - - - -

lua_pushboolean

-[-0, +1, –] -

void lua_pushboolean (lua_State *L, int b);
- -

-Pushes a boolean value with value b onto the stack. - - - - - -

lua_pushcclosure

-[-n, +1, m] -

void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
- -

-Pushes a new C closure onto the stack. - - -

-When a C function is created, -it is possible to associate some values with it, -thus creating a C closure (see §4.4); -these values are then accessible to the function whenever it is called. -To associate values with a C function, -first these values must be pushed onto the stack -(when there are multiple values, the first value is pushed first). -Then lua_pushcclosure -is called to create and push the C function onto the stack, -with the argument n telling how many values will be -associated with the function. -lua_pushcclosure also pops these values from the stack. - - -

-The maximum value for n is 255. - - -

-When n is zero, -this function creates a light C function, -which is just a pointer to the C function. -In that case, it never raises a memory error. - - - - - -

lua_pushcfunction

-[-0, +1, –] -

void lua_pushcfunction (lua_State *L, lua_CFunction f);
- -

-Pushes a C function onto the stack. -This function receives a pointer to a C function -and pushes onto the stack a Lua value of type function that, -when called, invokes the corresponding C function. - - -

-Any function to be callable by Lua must -follow the correct protocol to receive its parameters -and return its results (see lua_CFunction). - - - - - -

lua_pushfstring

-[-0, +1, e] -

const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
- -

-Pushes onto the stack a formatted string -and returns a pointer to this string. -It is similar to the ISO C function sprintf, -but has some important differences: - -

    - -
  • -You do not have to allocate space for the result: -the result is a Lua string and Lua takes care of memory allocation -(and deallocation, through garbage collection). -
    • - -
  • -The conversion specifiers are quite restricted. -There are no flags, widths, or precisions. -The conversion specifiers can only be -'%%' (inserts the character '%'), -'%s' (inserts a zero-terminated string, with no size restrictions), -'%f' (inserts a lua_Number), -'%I' (inserts a lua_Integer), -'%p' (inserts a pointer as a hexadecimal numeral), -'%d' (inserts an int), -'%c' (inserts an int as a one-byte character), and -'%U' (inserts a long int as a UTF-8 byte sequence). -
    • - -
- -

-Unlike other push functions, -this function checks for the stack space it needs, -including the slot for its result. - - - - - -

lua_pushglobaltable

-[-0, +1, –] -

void lua_pushglobaltable (lua_State *L);
- -

-Pushes the global environment onto the stack. - - - - - -

lua_pushinteger

-[-0, +1, –] -

void lua_pushinteger (lua_State *L, lua_Integer n);
- -

-Pushes an integer with value n onto the stack. - - - - - -

lua_pushlightuserdata

-[-0, +1, –] -

void lua_pushlightuserdata (lua_State *L, void *p);
- -

-Pushes a light userdata onto the stack. - - -

-Userdata represent C values in Lua. -A light userdata represents a pointer, a void*. -It is a value (like a number): -you do not create it, it has no individual metatable, -and it is not collected (as it was never created). -A light userdata is equal to "any" -light userdata with the same C address. - - - - - -

lua_pushliteral

-[-0, +1, m] -

const char *lua_pushliteral (lua_State *L, const char *s);
- -

-This macro is equivalent to lua_pushstring, -but should be used only when s is a literal string. - - - - - -

lua_pushlstring

-[-0, +1, m] -

const char *lua_pushlstring (lua_State *L, const char *s, size_t len);
- -

-Pushes the string pointed to by s with size len -onto the stack. -Lua makes (or reuses) an internal copy of the given string, -so the memory at s can be freed or reused immediately after -the function returns. -The string can contain any binary data, -including embedded zeros. - - -

-Returns a pointer to the internal copy of the string. - - - - - -

lua_pushnil

-[-0, +1, –] -

void lua_pushnil (lua_State *L);
- -

-Pushes a nil value onto the stack. - - - - - -

lua_pushnumber

-[-0, +1, –] -

void lua_pushnumber (lua_State *L, lua_Number n);
- -

-Pushes a float with value n onto the stack. - - - - - -

lua_pushstring

-[-0, +1, m] -

const char *lua_pushstring (lua_State *L, const char *s);
- -

-Pushes the zero-terminated string pointed to by s -onto the stack. -Lua makes (or reuses) an internal copy of the given string, -so the memory at s can be freed or reused immediately after -the function returns. - - -

-Returns a pointer to the internal copy of the string. - - -

-If s is NULL, pushes nil and returns NULL. - - - - - -

lua_pushthread

-[-0, +1, –] -

int lua_pushthread (lua_State *L);
- -

-Pushes the thread represented by L onto the stack. -Returns 1 if this thread is the main thread of its state. - - - - - -

lua_pushvalue

-[-0, +1, –] -

void lua_pushvalue (lua_State *L, int index);
- -

-Pushes a copy of the element at the given index -onto the stack. - - - - - -

lua_pushvfstring

-[-0, +1, m] -

const char *lua_pushvfstring (lua_State *L,
-                              const char *fmt,
-                              va_list argp);
- -

-Equivalent to lua_pushfstring, except that it receives a va_list -instead of a variable number of arguments. - - - - - -

lua_rawequal

-[-0, +0, –] -

int lua_rawequal (lua_State *L, int index1, int index2);
- -

-Returns 1 if the two values in indices index1 and -index2 are primitively equal -(that is, without calling the __eq metamethod). -Otherwise returns 0. -Also returns 0 if any of the indices are not valid. - - - - - -

lua_rawget

-[-1, +1, –] -

int lua_rawget (lua_State *L, int index);
- -

-Similar to lua_gettable, but does a raw access -(i.e., without metamethods). - - - - - -

lua_rawgeti

-[-0, +1, –] -

int lua_rawgeti (lua_State *L, int index, lua_Integer n);
- -

-Pushes onto the stack the value t[n], -where t is the table at the given index. -The access is raw, -that is, it does not invoke the __index metamethod. - - -

-Returns the type of the pushed value. - - - - - -

lua_rawgetp

-[-0, +1, –] -

int lua_rawgetp (lua_State *L, int index, const void *p);
- -

-Pushes onto the stack the value t[k], -where t is the table at the given index and -k is the pointer p represented as a light userdata. -The access is raw; -that is, it does not invoke the __index metamethod. - - -

-Returns the type of the pushed value. - - - - - -

lua_rawlen

-[-0, +0, –] -

size_t lua_rawlen (lua_State *L, int index);
- -

-Returns the raw "length" of the value at the given index: -for strings, this is the string length; -for tables, this is the result of the length operator ('#') -with no metamethods; -for userdata, this is the size of the block of memory allocated -for the userdata; -for other values, it is 0. - - - - - -

lua_rawset

-[-2, +0, m] -

void lua_rawset (lua_State *L, int index);
- -

-Similar to lua_settable, but does a raw assignment -(i.e., without metamethods). - - - - - -

lua_rawseti

-[-1, +0, m] -

void lua_rawseti (lua_State *L, int index, lua_Integer i);
- -

-Does the equivalent of t[i] = v, -where t is the table at the given index -and v is the value at the top of the stack. - - -

-This function pops the value from the stack. -The assignment is raw, -that is, it does not invoke the __newindex metamethod. - - - - - -

lua_rawsetp

-[-1, +0, m] -

void lua_rawsetp (lua_State *L, int index, const void *p);
- -

-Does the equivalent of t[p] = v, -where t is the table at the given index, -p is encoded as a light userdata, -and v is the value at the top of the stack. - - -

-This function pops the value from the stack. -The assignment is raw, -that is, it does not invoke __newindex metamethod. - - - - - -

lua_Reader

-
typedef const char * (*lua_Reader) (lua_State *L,
-                                    void *data,
-                                    size_t *size);
- -

-The reader function used by lua_load. -Every time it needs another piece of the chunk, -lua_load calls the reader, -passing along its data parameter. -The reader must return a pointer to a block of memory -with a new piece of the chunk -and set size to the block size. -The block must exist until the reader function is called again. -To signal the end of the chunk, -the reader must return NULL or set size to zero. -The reader function may return pieces of any size greater than zero. - - - - - -

lua_register

-[-0, +0, e] -

void lua_register (lua_State *L, const char *name, lua_CFunction f);
- -

-Sets the C function f as the new value of global name. -It is defined as a macro: - -

-     #define lua_register(L,n,f) \
-            (lua_pushcfunction(L, f), lua_setglobal(L, n))
-
- - - - -

lua_remove

-[-1, +0, –] -

void lua_remove (lua_State *L, int index);
- -

-Removes the element at the given valid index, -shifting down the elements above this index to fill the gap. -This function cannot be called with a pseudo-index, -because a pseudo-index is not an actual stack position. - - - - - -

lua_replace

-[-1, +0, –] -

void lua_replace (lua_State *L, int index);
- -

-Moves the top element into the given valid index -without shifting any element -(therefore replacing the value at that given index), -and then pops the top element. - - - - - -

lua_resume

-[-?, +?, –] -

int lua_resume (lua_State *L, lua_State *from, int nargs);
- -

-Starts and resumes a coroutine in the given thread L. - - -

-To start a coroutine, -you push onto the thread stack the main function plus any arguments; -then you call lua_resume, -with nargs being the number of arguments. -This call returns when the coroutine suspends or finishes its execution. -When it returns, the stack contains all values passed to lua_yield, -or all values returned by the body function. -lua_resume returns -LUA_YIELD if the coroutine yields, -LUA_OK if the coroutine finishes its execution -without errors, -or an error code in case of errors (see lua_pcall). - - -

-In case of errors, -the stack is not unwound, -so you can use the debug API over it. -The error object is on the top of the stack. - - -

-To resume a coroutine, -you remove any results from the last lua_yield, -put on its stack only the values to -be passed as results from yield, -and then call lua_resume. - - -

-The parameter from represents the coroutine that is resuming L. -If there is no such coroutine, -this parameter can be NULL. - - - - - -

lua_rotate

-[-0, +0, –] -

void lua_rotate (lua_State *L, int idx, int n);
- -

-Rotates the stack elements between the valid index idx -and the top of the stack. -The elements are rotated n positions in the direction of the top, -for a positive n, -or -n positions in the direction of the bottom, -for a negative n. -The absolute value of n must not be greater than the size -of the slice being rotated. -This function cannot be called with a pseudo-index, -because a pseudo-index is not an actual stack position. - - - - - -

lua_setallocf

-[-0, +0, –] -

void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
- -

-Changes the allocator function of a given state to f -with user data ud. - - - - - -

lua_setfield

-[-1, +0, e] -

void lua_setfield (lua_State *L, int index, const char *k);
- -

-Does the equivalent to t[k] = v, -where t is the value at the given index -and v is the value at the top of the stack. - - -

-This function pops the value from the stack. -As in Lua, this function may trigger a metamethod -for the "newindex" event (see §2.4). - - - - - -

lua_setglobal

-[-1, +0, e] -

void lua_setglobal (lua_State *L, const char *name);
- -

-Pops a value from the stack and -sets it as the new value of global name. - - - - - -

lua_seti

-[-1, +0, e] -

void lua_seti (lua_State *L, int index, lua_Integer n);
- -

-Does the equivalent to t[n] = v, -where t is the value at the given index -and v is the value at the top of the stack. - - -

-This function pops the value from the stack. -As in Lua, this function may trigger a metamethod -for the "newindex" event (see §2.4). - - - - - -

lua_setmetatable

-[-1, +0, –] -

void lua_setmetatable (lua_State *L, int index);
- -

-Pops a table from the stack and -sets it as the new metatable for the value at the given index. - - - - - -

lua_settable

-[-2, +0, e] -

void lua_settable (lua_State *L, int index);
- -

-Does the equivalent to t[k] = v, -where t is the value at the given index, -v is the value at the top of the stack, -and k is the value just below the top. - - -

-This function pops both the key and the value from the stack. -As in Lua, this function may trigger a metamethod -for the "newindex" event (see §2.4). - - - - - -

lua_settop

-[-?, +?, –] -

void lua_settop (lua_State *L, int index);
- -

-Accepts any index, or 0, -and sets the stack top to this index. -If the new top is larger than the old one, -then the new elements are filled with nil. -If index is 0, then all stack elements are removed. - - - - - -

lua_setuservalue

-[-1, +0, –] -

void lua_setuservalue (lua_State *L, int index);
- -

-Pops a value from the stack and sets it as -the new value associated to the full userdata at the given index. - - - - - -

lua_State

-
typedef struct lua_State lua_State;
- -

-An opaque structure that points to a thread and indirectly -(through the thread) to the whole state of a Lua interpreter. -The Lua library is fully reentrant: -it has no global variables. -All information about a state is accessible through this structure. - - -

-A pointer to this structure must be passed as the first argument to -every function in the library, except to lua_newstate, -which creates a Lua state from scratch. - - - - - -

lua_status

-[-0, +0, –] -

int lua_status (lua_State *L);
- -

-Returns the status of the thread L. - - -

-The status can be 0 (LUA_OK) for a normal thread, -an error code if the thread finished the execution -of a lua_resume with an error, -or LUA_YIELD if the thread is suspended. - - -

-You can only call functions in threads with status LUA_OK. -You can resume threads with status LUA_OK -(to start a new coroutine) or LUA_YIELD -(to resume a coroutine). - - - - - -

lua_stringtonumber

-[-0, +1, –] -

size_t lua_stringtonumber (lua_State *L, const char *s);
- -

-Converts the zero-terminated string s to a number, -pushes that number into the stack, -and returns the total size of the string, -that is, its length plus one. -The conversion can result in an integer or a float, -according to the lexical conventions of Lua (see §3.1). -The string may have leading and trailing spaces and a sign. -If the string is not a valid numeral, -returns 0 and pushes nothing. -(Note that the result can be used as a boolean, -true if the conversion succeeds.) - - - - - -

lua_toboolean

-[-0, +0, –] -

int lua_toboolean (lua_State *L, int index);
- -

-Converts the Lua value at the given index to a C boolean -value (0 or 1). -Like all tests in Lua, -lua_toboolean returns true for any Lua value -different from false and nil; -otherwise it returns false. -(If you want to accept only actual boolean values, -use lua_isboolean to test the value's type.) - - - - - -

lua_tocfunction

-[-0, +0, –] -

lua_CFunction lua_tocfunction (lua_State *L, int index);
- -

-Converts a value at the given index to a C function. -That value must be a C function; -otherwise, returns NULL. - - - - - -

lua_tointeger

-[-0, +0, –] -

lua_Integer lua_tointeger (lua_State *L, int index);
- -

-Equivalent to lua_tointegerx with isnum equal to NULL. - - - - - -

lua_tointegerx

-[-0, +0, –] -

lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);
- -

-Converts the Lua value at the given index -to the signed integral type lua_Integer. -The Lua value must be an integer, -or a number or string convertible to an integer (see §3.4.3); -otherwise, lua_tointegerx returns 0. - - -

-If isnum is not NULL, -its referent is assigned a boolean value that -indicates whether the operation succeeded. - - - - - -

lua_tolstring

-[-0, +0, m] -

const char *lua_tolstring (lua_State *L, int index, size_t *len);
- -

-Converts the Lua value at the given index to a C string. -If len is not NULL, -it sets *len with the string length. -The Lua value must be a string or a number; -otherwise, the function returns NULL. -If the value is a number, -then lua_tolstring also -changes the actual value in the stack to a string. -(This change confuses lua_next -when lua_tolstring is applied to keys during a table traversal.) - - -

-lua_tolstring returns a pointer -to a string inside the Lua state. -This string always has a zero ('\0') -after its last character (as in C), -but can contain other zeros in its body. - - -

-Because Lua has garbage collection, -there is no guarantee that the pointer returned by lua_tolstring -will be valid after the corresponding Lua value is removed from the stack. - - - - - -

lua_tonumber

-[-0, +0, –] -

lua_Number lua_tonumber (lua_State *L, int index);
- -

-Equivalent to lua_tonumberx with isnum equal to NULL. - - - - - -

lua_tonumberx

-[-0, +0, –] -

lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);
- -

-Converts the Lua value at the given index -to the C type lua_Number (see lua_Number). -The Lua value must be a number or a string convertible to a number -(see §3.4.3); -otherwise, lua_tonumberx returns 0. - - -

-If isnum is not NULL, -its referent is assigned a boolean value that -indicates whether the operation succeeded. - - - - - -

lua_topointer

-[-0, +0, –] -

const void *lua_topointer (lua_State *L, int index);
- -

-Converts the value at the given index to a generic -C pointer (void*). -The value can be a userdata, a table, a thread, or a function; -otherwise, lua_topointer returns NULL. -Different objects will give different pointers. -There is no way to convert the pointer back to its original value. - - -

-Typically this function is used only for hashing and debug information. - - - - - -

lua_tostring

-[-0, +0, m] -

const char *lua_tostring (lua_State *L, int index);
- -

-Equivalent to lua_tolstring with len equal to NULL. - - - - - -

lua_tothread

-[-0, +0, –] -

lua_State *lua_tothread (lua_State *L, int index);
- -

-Converts the value at the given index to a Lua thread -(represented as lua_State*). -This value must be a thread; -otherwise, the function returns NULL. - - - - - -

lua_touserdata

-[-0, +0, –] -

void *lua_touserdata (lua_State *L, int index);
- -

-If the value at the given index is a full userdata, -returns its block address. -If the value is a light userdata, -returns its pointer. -Otherwise, returns NULL. - - - - - -

lua_type

-[-0, +0, –] -

int lua_type (lua_State *L, int index);
- -

-Returns the type of the value in the given valid index, -or LUA_TNONE for a non-valid (but acceptable) index. -The types returned by lua_type are coded by the following constants -defined in lua.h: -LUA_TNIL (0), -LUA_TNUMBER, -LUA_TBOOLEAN, -LUA_TSTRING, -LUA_TTABLE, -LUA_TFUNCTION, -LUA_TUSERDATA, -LUA_TTHREAD, -and -LUA_TLIGHTUSERDATA. - - - - - -

lua_typename

-[-0, +0, –] -

const char *lua_typename (lua_State *L, int tp);
- -

-Returns the name of the type encoded by the value tp, -which must be one the values returned by lua_type. - - - - - -

lua_Unsigned

-
typedef ... lua_Unsigned;
- -

-The unsigned version of lua_Integer. - - - - - -

lua_upvalueindex

-[-0, +0, –] -

int lua_upvalueindex (int i);
- -

-Returns the pseudo-index that represents the i-th upvalue of -the running function (see §4.4). - - - - - -

lua_version

-[-0, +0, –] -

const lua_Number *lua_version (lua_State *L);
- -

-Returns the address of the version number -(a C static variable) -stored in the Lua core. -When called with a valid lua_State, -returns the address of the version used to create that state. -When called with NULL, -returns the address of the version running the call. - - - - - -

lua_Writer

-
typedef int (*lua_Writer) (lua_State *L,
-                           const void* p,
-                           size_t sz,
-                           void* ud);
- -

-The type of the writer function used by lua_dump. -Every time it produces another piece of chunk, -lua_dump calls the writer, -passing along the buffer to be written (p), -its size (sz), -and the data parameter supplied to lua_dump. - - -

-The writer returns an error code: -0 means no errors; -any other value means an error and stops lua_dump from -calling the writer again. - - - - - -

lua_xmove

-[-?, +?, –] -

void lua_xmove (lua_State *from, lua_State *to, int n);
- -

-Exchange values between different threads of the same state. - - -

-This function pops n values from the stack from, -and pushes them onto the stack to. - - - - - -

lua_yield

-[-?, +?, e] -

int lua_yield (lua_State *L, int nresults);
- -

-This function is equivalent to lua_yieldk, -but it has no continuation (see §4.7). -Therefore, when the thread resumes, -it continues the function that called -the function calling lua_yield. - - - - - -

lua_yieldk

-[-?, +?, e] -

int lua_yieldk (lua_State *L,
-                int nresults,
-                lua_KContext ctx,
-                lua_KFunction k);
- -

-Yields a coroutine (thread). - - -

-When a C function calls lua_yieldk, -the running coroutine suspends its execution, -and the call to lua_resume that started this coroutine returns. -The parameter nresults is the number of values from the stack -that will be passed as results to lua_resume. - - -

-When the coroutine is resumed again, -Lua calls the given continuation function k to continue -the execution of the C function that yielded (see §4.7). -This continuation function receives the same stack -from the previous function, -with the n results removed and -replaced by the arguments passed to lua_resume. -Moreover, -the continuation function receives the value ctx -that was passed to lua_yieldk. - - -

-Usually, this function does not return; -when the coroutine eventually resumes, -it continues executing the continuation function. -However, there is one special case, -which is when this function is called -from inside a line or a count hook (see §4.9). -In that case, lua_yieldk should be called with no continuation -(probably in the form of lua_yield) and no results, -and the hook should return immediately after the call. -Lua will yield and, -when the coroutine resumes again, -it will continue the normal execution -of the (Lua) function that triggered the hook. - - -

-This function can raise an error if it is called from a thread -with a pending C call with no continuation function, -or it is called from a thread that is not running inside a resume -(e.g., the main thread). - - - - - - - -

4.9 – The Debug Interface

- -

-Lua has no built-in debugging facilities. -Instead, it offers a special interface -by means of functions and hooks. -This interface allows the construction of different -kinds of debuggers, profilers, and other tools -that need "inside information" from the interpreter. - - - -

lua_Debug

-
typedef struct lua_Debug {
-  int event;
-  const char *name;           /* (n) */
-  const char *namewhat;       /* (n) */
-  const char *what;           /* (S) */
-  const char *source;         /* (S) */
-  int currentline;            /* (l) */
-  int linedefined;            /* (S) */
-  int lastlinedefined;        /* (S) */
-  unsigned char nups;         /* (u) number of upvalues */
-  unsigned char nparams;      /* (u) number of parameters */
-  char isvararg;              /* (u) */
-  char istailcall;            /* (t) */
-  char short_src[LUA_IDSIZE]; /* (S) */
-  /* private part */
-  other fields
-} lua_Debug;
- -

-A structure used to carry different pieces of -information about a function or an activation record. -lua_getstack fills only the private part -of this structure, for later use. -To fill the other fields of lua_Debug with useful information, -call lua_getinfo. - - -

-The fields of lua_Debug have the following meaning: - -

    - -
  • source: -the name of the chunk that created the function. -If source starts with a '@', -it means that the function was defined in a file where -the file name follows the '@'. -If source starts with a '=', -the remainder of its contents describe the source in a user-dependent manner. -Otherwise, -the function was defined in a string where -source is that string. -
    • - -
  • short_src: -a "printable" version of source, to be used in error messages. -
    • - -
  • linedefined: -the line number where the definition of the function starts. -
    • - -
  • lastlinedefined: -the line number where the definition of the function ends. -
    • - -
  • what: -the string "Lua" if the function is a Lua function, -"C" if it is a C function, -"main" if it is the main part of a chunk. -
    • - -
  • currentline: -the current line where the given function is executing. -When no line information is available, -currentline is set to -1. -
    • - -
  • name: -a reasonable name for the given function. -Because functions in Lua are first-class values, -they do not have a fixed name: -some functions can be the value of multiple global variables, -while others can be stored only in a table field. -The lua_getinfo function checks how the function was -called to find a suitable name. -If it cannot find a name, -then name is set to NULL. -
    • - -
  • namewhat: -explains the name field. -The value of namewhat can be -"global", "local", "method", -"field", "upvalue", or "" (the empty string), -according to how the function was called. -(Lua uses the empty string when no other option seems to apply.) -
    • - -
  • istailcall: -true if this function invocation was called by a tail call. -In this case, the caller of this level is not in the stack. -
    • - -
  • nups: -the number of upvalues of the function. -
    • - -
  • nparams: -the number of fixed parameters of the function -(always 0 for C functions). -
    • - -
  • isvararg: -true if the function is a vararg function -(always true for C functions). -
    • - -
- - - - -

lua_gethook

-[-0, +0, –] -

lua_Hook lua_gethook (lua_State *L);
- -

-Returns the current hook function. - - - - - -

lua_gethookcount

-[-0, +0, –] -

int lua_gethookcount (lua_State *L);
- -

-Returns the current hook count. - - - - - -

lua_gethookmask

-[-0, +0, –] -

int lua_gethookmask (lua_State *L);
- -

-Returns the current hook mask. - - - - - -

lua_getinfo

-[-(0|1), +(0|1|2), e] -

int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
- -

-Gets information about a specific function or function invocation. - - -

-To get information about a function invocation, -the parameter ar must be a valid activation record that was -filled by a previous call to lua_getstack or -given as argument to a hook (see lua_Hook). - - -

-To get information about a function, you push it onto the stack -and start the what string with the character '>'. -(In that case, -lua_getinfo pops the function from the top of the stack.) -For instance, to know in which line a function f was defined, -you can write the following code: - -

-     lua_Debug ar;
-     lua_getglobal(L, "f");  /* get global 'f' */
-     lua_getinfo(L, ">S", &ar);
-     printf("%d\n", ar.linedefined);
-
- -

-Each character in the string what -selects some fields of the structure ar to be filled or -a value to be pushed on the stack: - -

    - -
  • 'n': fills in the field name and namewhat; -
    • - -
  • 'S': -fills in the fields source, short_src, -linedefined, lastlinedefined, and what; -
    • - -
  • 'l': fills in the field currentline; -
    • - -
  • 't': fills in the field istailcall; -
    • - -
  • 'u': fills in the fields -nups, nparams, and isvararg; -
    • - -
  • 'f': -pushes onto the stack the function that is -running at the given level; -
    • - -
  • 'L': -pushes onto the stack a table whose indices are the -numbers of the lines that are valid on the function. -(A valid line is a line with some associated code, -that is, a line where you can put a break point. -Non-valid lines include empty lines and comments.) - - -

    -If this option is given together with option 'f', -its table is pushed after the function. -

    • - -
- -

-This function returns 0 on error -(for instance, an invalid option in what). - - - - - -

lua_getlocal

-[-0, +(0|1), –] -

const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);
- -

-Gets information about a local variable of -a given activation record or a given function. - - -

-In the first case, -the parameter ar must be a valid activation record that was -filled by a previous call to lua_getstack or -given as argument to a hook (see lua_Hook). -The index n selects which local variable to inspect; -see debug.getlocal for details about variable indices -and names. - - -

-lua_getlocal pushes the variable's value onto the stack -and returns its name. - - -

-In the second case, ar must be NULL and the function -to be inspected must be at the top of the stack. -In this case, only parameters of Lua functions are visible -(as there is no information about what variables are active) -and no values are pushed onto the stack. - - -

-Returns NULL (and pushes nothing) -when the index is greater than -the number of active local variables. - - - - - -

lua_getstack

-[-0, +0, –] -

int lua_getstack (lua_State *L, int level, lua_Debug *ar);
- -

-Gets information about the interpreter runtime stack. - - -

-This function fills parts of a lua_Debug structure with -an identification of the activation record -of the function executing at a given level. -Level 0 is the current running function, -whereas level n+1 is the function that has called level n -(except for tail calls, which do not count on the stack). -When there are no errors, lua_getstack returns 1; -when called with a level greater than the stack depth, -it returns 0. - - - - - -

lua_getupvalue

-[-0, +(0|1), –] -

const char *lua_getupvalue (lua_State *L, int funcindex, int n);
- -

-Gets information about the n-th upvalue -of the closure at index funcindex. -It pushes the upvalue's value onto the stack -and returns its name. -Returns NULL (and pushes nothing) -when the index n is greater than the number of upvalues. - - -

-For C functions, this function uses the empty string "" -as a name for all upvalues. -(For Lua functions, -upvalues are the external local variables that the function uses, -and that are consequently included in its closure.) - - -

-Upvalues have no particular order, -as they are active through the whole function. -They are numbered in an arbitrary order. - - - - - -

lua_Hook

-
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
- -

-Type for debugging hook functions. - - -

-Whenever a hook is called, its ar argument has its field -event set to the specific event that triggered the hook. -Lua identifies these events with the following constants: -LUA_HOOKCALL, LUA_HOOKRET, -LUA_HOOKTAILCALL, LUA_HOOKLINE, -and LUA_HOOKCOUNT. -Moreover, for line events, the field currentline is also set. -To get the value of any other field in ar, -the hook must call lua_getinfo. - - -

-For call events, event can be LUA_HOOKCALL, -the normal value, or LUA_HOOKTAILCALL, for a tail call; -in this case, there will be no corresponding return event. - - -

-While Lua is running a hook, it disables other calls to hooks. -Therefore, if a hook calls back Lua to execute a function or a chunk, -this execution occurs without any calls to hooks. - - -

-Hook functions cannot have continuations, -that is, they cannot call lua_yieldk, -lua_pcallk, or lua_callk with a non-null k. - - -

-Hook functions can yield under the following conditions: -Only count and line events can yield; -to yield, a hook function must finish its execution -calling lua_yield with nresults equal to zero -(that is, with no values). - - - - - -

lua_sethook

-[-0, +0, –] -

void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);
- -

-Sets the debugging hook function. - - -

-Argument f is the hook function. -mask specifies on which events the hook will be called: -it is formed by a bitwise OR of the constants -LUA_MASKCALL, -LUA_MASKRET, -LUA_MASKLINE, -and LUA_MASKCOUNT. -The count argument is only meaningful when the mask -includes LUA_MASKCOUNT. -For each event, the hook is called as explained below: - -

    - -
  • The call hook: is called when the interpreter calls a function. -The hook is called just after Lua enters the new function, -before the function gets its arguments. -
    • - -
  • The return hook: is called when the interpreter returns from a function. -The hook is called just before Lua leaves the function. -There is no standard way to access the values -to be returned by the function. -
    • - -
  • The line hook: is called when the interpreter is about to -start the execution of a new line of code, -or when it jumps back in the code (even to the same line). -(This event only happens while Lua is executing a Lua function.) -
    • - -
  • The count hook: is called after the interpreter executes every -count instructions. -(This event only happens while Lua is executing a Lua function.) -
    • - -
- -

-A hook is disabled by setting mask to zero. - - - - - -

lua_setlocal

-[-(0|1), +0, –] -

const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);
- -

-Sets the value of a local variable of a given activation record. -It assigns the value at the top of the stack -to the variable and returns its name. -It also pops the value from the stack. - - -

-Returns NULL (and pops nothing) -when the index is greater than -the number of active local variables. - - -

-Parameters ar and n are as in function lua_getlocal. - - - - - -

lua_setupvalue

-[-(0|1), +0, –] -

const char *lua_setupvalue (lua_State *L, int funcindex, int n);
- -

-Sets the value of a closure's upvalue. -It assigns the value at the top of the stack -to the upvalue and returns its name. -It also pops the value from the stack. - - -

-Returns NULL (and pops nothing) -when the index n is greater than the number of upvalues. - - -

-Parameters funcindex and n are as in function lua_getupvalue. - - - - - -

lua_upvalueid

-[-0, +0, –] -

void *lua_upvalueid (lua_State *L, int funcindex, int n);
- -

-Returns a unique identifier for the upvalue numbered n -from the closure at index funcindex. - - -

-These unique identifiers allow a program to check whether different -closures share upvalues. -Lua closures that share an upvalue -(that is, that access a same external local variable) -will return identical ids for those upvalue indices. - - -

-Parameters funcindex and n are as in function lua_getupvalue, -but n cannot be greater than the number of upvalues. - - - - - -

lua_upvaluejoin

-[-0, +0, –] -

void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
-                                    int funcindex2, int n2);
- -

-Make the n1-th upvalue of the Lua closure at index funcindex1 -refer to the n2-th upvalue of the Lua closure at index funcindex2. - - - - - - - -

5 – The Auxiliary Library

- -

- -The auxiliary library provides several convenient functions -to interface C with Lua. -While the basic API provides the primitive functions for all -interactions between C and Lua, -the auxiliary library provides higher-level functions for some -common tasks. - - -

-All functions and types from the auxiliary library -are defined in header file lauxlib.h and -have a prefix luaL_. - - -

-All functions in the auxiliary library are built on -top of the basic API, -and so they provide nothing that cannot be done with that API. -Nevertheless, the use of the auxiliary library ensures -more consistency to your code. - - -

-Several functions in the auxiliary library use internally some -extra stack slots. -When a function in the auxiliary library uses less than five slots, -it does not check the stack size; -it simply assumes that there are enough slots. - - -

-Several functions in the auxiliary library are used to -check C function arguments. -Because the error message is formatted for arguments -(e.g., "bad argument #1"), -you should not use these functions for other stack values. - - -

-Functions called luaL_check* -always raise an error if the check is not satisfied. - - - -

5.1 – Functions and Types

- -

-Here we list all functions and types from the auxiliary library -in alphabetical order. - - - -

luaL_addchar

-[-?, +?, m] -

void luaL_addchar (luaL_Buffer *B, char c);
- -

-Adds the byte c to the buffer B -(see luaL_Buffer). - - - - - -

luaL_addlstring

-[-?, +?, m] -

void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
- -

-Adds the string pointed to by s with length l to -the buffer B -(see luaL_Buffer). -The string can contain embedded zeros. - - - - - -

luaL_addsize

-[-?, +?, –] -

void luaL_addsize (luaL_Buffer *B, size_t n);
- -

-Adds to the buffer B (see luaL_Buffer) -a string of length n previously copied to the -buffer area (see luaL_prepbuffer). - - - - - -

luaL_addstring

-[-?, +?, m] -

void luaL_addstring (luaL_Buffer *B, const char *s);
- -

-Adds the zero-terminated string pointed to by s -to the buffer B -(see luaL_Buffer). - - - - - -

luaL_addvalue

-[-1, +?, m] -

void luaL_addvalue (luaL_Buffer *B);
- -

-Adds the value at the top of the stack -to the buffer B -(see luaL_Buffer). -Pops the value. - - -

-This is the only function on string buffers that can (and must) -be called with an extra element on the stack, -which is the value to be added to the buffer. - - - - - -

luaL_argcheck

-[-0, +0, v] -

void luaL_argcheck (lua_State *L,
-                    int cond,
-                    int arg,
-                    const char *extramsg);
- -

-Checks whether cond is true. -If it is not, raises an error with a standard message (see luaL_argerror). - - - - - -

luaL_argerror

-[-0, +0, v] -

int luaL_argerror (lua_State *L, int arg, const char *extramsg);
- -

-Raises an error reporting a problem with argument arg -of the C function that called it, -using a standard message -that includes extramsg as a comment: - -

-     bad argument #arg to 'funcname' (extramsg)
-

-This function never returns. - - - - - -

luaL_Buffer

-
typedef struct luaL_Buffer luaL_Buffer;
- -

-Type for a string buffer. - - -

-A string buffer allows C code to build Lua strings piecemeal. -Its pattern of use is as follows: - -

    - -
  • First declare a variable b of type luaL_Buffer.
    • - -
  • Then initialize it with a call luaL_buffinit(L, &b).
    • - -
  • -Then add string pieces to the buffer calling any of -the luaL_add* functions. -
    • - -
  • -Finish by calling luaL_pushresult(&b). -This call leaves the final string on the top of the stack. -
    • - -
- -

-If you know beforehand the total size of the resulting string, -you can use the buffer like this: - -

    - -
  • First declare a variable b of type luaL_Buffer.
    • - -
  • Then initialize it and preallocate a space of -size sz with a call luaL_buffinitsize(L, &b, sz).
    • - -
  • Then copy the string into that space.
    • - -
  • -Finish by calling luaL_pushresultsize(&b, sz), -where sz is the total size of the resulting string -copied into that space. -
    • - -
- -

-During its normal operation, -a string buffer uses a variable number of stack slots. -So, while using a buffer, you cannot assume that you know where -the top of the stack is. -You can use the stack between successive calls to buffer operations -as long as that use is balanced; -that is, -when you call a buffer operation, -the stack is at the same level -it was immediately after the previous buffer operation. -(The only exception to this rule is luaL_addvalue.) -After calling luaL_pushresult the stack is back to its -level when the buffer was initialized, -plus the final string on its top. - - - - - -

luaL_buffinit

-[-0, +0, –] -

void luaL_buffinit (lua_State *L, luaL_Buffer *B);
- -

-Initializes a buffer B. -This function does not allocate any space; -the buffer must be declared as a variable -(see luaL_Buffer). - - - - - -

luaL_buffinitsize

-[-?, +?, m] -

char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);
- -

-Equivalent to the sequence -luaL_buffinit, luaL_prepbuffsize. - - - - - -

luaL_callmeta

-[-0, +(0|1), e] -

int luaL_callmeta (lua_State *L, int obj, const char *e);
- -

-Calls a metamethod. - - -

-If the object at index obj has a metatable and this -metatable has a field e, -this function calls this field passing the object as its only argument. -In this case this function returns true and pushes onto the -stack the value returned by the call. -If there is no metatable or no metamethod, -this function returns false (without pushing any value on the stack). - - - - - -

luaL_checkany

-[-0, +0, v] -

void luaL_checkany (lua_State *L, int arg);
- -

-Checks whether the function has an argument -of any type (including nil) at position arg. - - - - - -

luaL_checkinteger

-[-0, +0, v] -

lua_Integer luaL_checkinteger (lua_State *L, int arg);
- -

-Checks whether the function argument arg is an integer -(or can be converted to an integer) -and returns this integer cast to a lua_Integer. - - - - - -

luaL_checklstring

-[-0, +0, v] -

const char *luaL_checklstring (lua_State *L, int arg, size_t *l);
- -

-Checks whether the function argument arg is a string -and returns this string; -if l is not NULL fills *l -with the string's length. - - -

-This function uses lua_tolstring to get its result, -so all conversions and caveats of that function apply here. - - - - - -

luaL_checknumber

-[-0, +0, v] -

lua_Number luaL_checknumber (lua_State *L, int arg);
- -

-Checks whether the function argument arg is a number -and returns this number. - - - - - -

luaL_checkoption

-[-0, +0, v] -

int luaL_checkoption (lua_State *L,
-                      int arg,
-                      const char *def,
-                      const char *const lst[]);
- -

-Checks whether the function argument arg is a string and -searches for this string in the array lst -(which must be NULL-terminated). -Returns the index in the array where the string was found. -Raises an error if the argument is not a string or -if the string cannot be found. - - -

-If def is not NULL, -the function uses def as a default value when -there is no argument arg or when this argument is nil. - - -

-This is a useful function for mapping strings to C enums. -(The usual convention in Lua libraries is -to use strings instead of numbers to select options.) - - - - - -

luaL_checkstack

-[-0, +0, v] -

void luaL_checkstack (lua_State *L, int sz, const char *msg);
- -

-Grows the stack size to top + sz elements, -raising an error if the stack cannot grow to that size. -msg is an additional text to go into the error message -(or NULL for no additional text). - - - - - -

luaL_checkstring

-[-0, +0, v] -

const char *luaL_checkstring (lua_State *L, int arg);
- -

-Checks whether the function argument arg is a string -and returns this string. - - -

-This function uses lua_tolstring to get its result, -so all conversions and caveats of that function apply here. - - - - - -

luaL_checktype

-[-0, +0, v] -

void luaL_checktype (lua_State *L, int arg, int t);
- -

-Checks whether the function argument arg has type t. -See lua_type for the encoding of types for t. - - - - - -

luaL_checkudata

-[-0, +0, v] -

void *luaL_checkudata (lua_State *L, int arg, const char *tname);
- -

-Checks whether the function argument arg is a userdata -of the type tname (see luaL_newmetatable) and -returns the userdata address (see lua_touserdata). - - - - - -

luaL_checkversion

-[-0, +0, v] -

void luaL_checkversion (lua_State *L);
- -

-Checks whether the core running the call, -the core that created the Lua state, -and the code making the call are all using the same version of Lua. -Also checks whether the core running the call -and the core that created the Lua state -are using the same address space. - - - - - -

luaL_dofile

-[-0, +?, e] -

int luaL_dofile (lua_State *L, const char *filename);
- -

-Loads and runs the given file. -It is defined as the following macro: - -

-     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
-

-It returns false if there are no errors -or true in case of errors. - - - - - -

luaL_dostring

-[-0, +?, –] -

int luaL_dostring (lua_State *L, const char *str);
- -

-Loads and runs the given string. -It is defined as the following macro: - -

-     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
-

-It returns false if there are no errors -or true in case of errors. - - - - - -

luaL_error

-[-0, +0, v] -

int luaL_error (lua_State *L, const char *fmt, ...);
- -

-Raises an error. -The error message format is given by fmt -plus any extra arguments, -following the same rules of lua_pushfstring. -It also adds at the beginning of the message the file name and -the line number where the error occurred, -if this information is available. - - -

-This function never returns, -but it is an idiom to use it in C functions -as return luaL_error(args). - - - - - -

luaL_execresult

-[-0, +3, m] -

int luaL_execresult (lua_State *L, int stat);
- -

-This function produces the return values for -process-related functions in the standard library -(os.execute and io.close). - - - - - -

luaL_fileresult

-[-0, +(1|3), m] -

int luaL_fileresult (lua_State *L, int stat, const char *fname);
- -

-This function produces the return values for -file-related functions in the standard library -(io.open, os.rename, file:seek, etc.). - - - - - -

luaL_getmetafield

-[-0, +(0|1), m] -

int luaL_getmetafield (lua_State *L, int obj, const char *e);
- -

-Pushes onto the stack the field e from the metatable -of the object at index obj and returns the type of the pushed value. -If the object does not have a metatable, -or if the metatable does not have this field, -pushes nothing and returns LUA_TNIL. - - - - - -

luaL_getmetatable

-[-0, +1, m] -

int luaL_getmetatable (lua_State *L, const char *tname);
- -

-Pushes onto the stack the metatable associated with name tname -in the registry (see luaL_newmetatable) -(nil if there is no metatable associated with that name). -Returns the type of the pushed value. - - - - - -

luaL_getsubtable

-[-0, +1, e] -

int luaL_getsubtable (lua_State *L, int idx, const char *fname);
- -

-Ensures that the value t[fname], -where t is the value at index idx, -is a table, -and pushes that table onto the stack. -Returns true if it finds a previous table there -and false if it creates a new table. - - - - - -

luaL_gsub

-[-0, +1, m] -

const char *luaL_gsub (lua_State *L,
-                       const char *s,
-                       const char *p,
-                       const char *r);
- -

-Creates a copy of string s by replacing -any occurrence of the string p -with the string r. -Pushes the resulting string on the stack and returns it. - - - - - -

luaL_len

-[-0, +0, e] -

lua_Integer luaL_len (lua_State *L, int index);
- -

-Returns the "length" of the value at the given index -as a number; -it is equivalent to the '#' operator in Lua (see §3.4.7). -Raises an error if the result of the operation is not an integer. -(This case only can happen through metamethods.) - - - - - -

luaL_loadbuffer

-[-0, +1, –] -

int luaL_loadbuffer (lua_State *L,
-                     const char *buff,
-                     size_t sz,
-                     const char *name);
- -

-Equivalent to luaL_loadbufferx with mode equal to NULL. - - - - - -

luaL_loadbufferx

-[-0, +1, –] -

int luaL_loadbufferx (lua_State *L,
-                      const char *buff,
-                      size_t sz,
-                      const char *name,
-                      const char *mode);
- -

-Loads a buffer as a Lua chunk. -This function uses lua_load to load the chunk in the -buffer pointed to by buff with size sz. - - -

-This function returns the same results as lua_load. -name is the chunk name, -used for debug information and error messages. -The string mode works as in function lua_load. - - - - - -

luaL_loadfile

-[-0, +1, m] -

int luaL_loadfile (lua_State *L, const char *filename);
- -

-Equivalent to luaL_loadfilex with mode equal to NULL. - - - - - -

luaL_loadfilex

-[-0, +1, m] -

int luaL_loadfilex (lua_State *L, const char *filename,
-                                            const char *mode);
- -

-Loads a file as a Lua chunk. -This function uses lua_load to load the chunk in the file -named filename. -If filename is NULL, -then it loads from the standard input. -The first line in the file is ignored if it starts with a #. - - -

-The string mode works as in function lua_load. - - -

-This function returns the same results as lua_load, -but it has an extra error code LUA_ERRFILE -for file-related errors -(e.g., it cannot open or read the file). - - -

-As lua_load, this function only loads the chunk; -it does not run it. - - - - - -

luaL_loadstring

-[-0, +1, –] -

int luaL_loadstring (lua_State *L, const char *s);
- -

-Loads a string as a Lua chunk. -This function uses lua_load to load the chunk in -the zero-terminated string s. - - -

-This function returns the same results as lua_load. - - -

-Also as lua_load, this function only loads the chunk; -it does not run it. - - - - - -

luaL_newlib

-[-0, +1, m] -

void luaL_newlib (lua_State *L, const luaL_Reg l[]);
- -

-Creates a new table and registers there -the functions in list l. - - -

-It is implemented as the following macro: - -

-     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
-

-The array l must be the actual array, -not a pointer to it. - - - - - -

luaL_newlibtable

-[-0, +1, m] -

void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);
- -

-Creates a new table with a size optimized -to store all entries in the array l -(but does not actually store them). -It is intended to be used in conjunction with luaL_setfuncs -(see luaL_newlib). - - -

-It is implemented as a macro. -The array l must be the actual array, -not a pointer to it. - - - - - -

luaL_newmetatable

-[-0, +1, m] -

int luaL_newmetatable (lua_State *L, const char *tname);
- -

-If the registry already has the key tname, -returns 0. -Otherwise, -creates a new table to be used as a metatable for userdata, -adds to this new table the pair __name = tname, -adds to the registry the pair [tname] = new table, -and returns 1. -(The entry __name is used by some error-reporting functions.) - - -

-In both cases pushes onto the stack the final value associated -with tname in the registry. - - - - - -

luaL_newstate

-[-0, +0, –] -

lua_State *luaL_newstate (void);
- -

-Creates a new Lua state. -It calls lua_newstate with an -allocator based on the standard C realloc function -and then sets a panic function (see §4.6) that prints -an error message to the standard error output in case of fatal -errors. - - -

-Returns the new state, -or NULL if there is a memory allocation error. - - - - - -

luaL_openlibs

-[-0, +0, e] -

void luaL_openlibs (lua_State *L);
- -

-Opens all standard Lua libraries into the given state. - - - - - -

luaL_opt

-[-0, +0, e] -

T luaL_opt (L, func, arg, dflt);
- -

-This macro is defined as follows: - -

-     (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
-

-In words, if the argument arg is nil or absent, -the macro results in the default dflt. -Otherwise, it results in the result of calling func -with the state L and the argument index arg as -arguments. -Note that it evaluates the expression dflt only if needed. - - - - - -

luaL_optinteger

-[-0, +0, v] -

lua_Integer luaL_optinteger (lua_State *L,
-                             int arg,
-                             lua_Integer d);
- -

-If the function argument arg is an integer -(or convertible to an integer), -returns this integer. -If this argument is absent or is nil, -returns d. -Otherwise, raises an error. - - - - - -

luaL_optlstring

-[-0, +0, v] -

const char *luaL_optlstring (lua_State *L,
-                             int arg,
-                             const char *d,
-                             size_t *l);
- -

-If the function argument arg is a string, -returns this string. -If this argument is absent or is nil, -returns d. -Otherwise, raises an error. - - -

-If l is not NULL, -fills the position *l with the result's length. -If the result is NULL -(only possible when returning d and d == NULL), -its length is considered zero. - - -

-This function uses lua_tolstring to get its result, -so all conversions and caveats of that function apply here. - - - - - -

luaL_optnumber

-[-0, +0, v] -

lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);
- -

-If the function argument arg is a number, -returns this number. -If this argument is absent or is nil, -returns d. -Otherwise, raises an error. - - - - - -

luaL_optstring

-[-0, +0, v] -

const char *luaL_optstring (lua_State *L,
-                            int arg,
-                            const char *d);
- -

-If the function argument arg is a string, -returns this string. -If this argument is absent or is nil, -returns d. -Otherwise, raises an error. - - - - - -

luaL_prepbuffer

-[-?, +?, m] -

char *luaL_prepbuffer (luaL_Buffer *B);
- -

-Equivalent to luaL_prepbuffsize -with the predefined size LUAL_BUFFERSIZE. - - - - - -

luaL_prepbuffsize

-[-?, +?, m] -

char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);
- -

-Returns an address to a space of size sz -where you can copy a string to be added to buffer B -(see luaL_Buffer). -After copying the string into this space you must call -luaL_addsize with the size of the string to actually add -it to the buffer. - - - - - -

luaL_pushresult

-[-?, +1, m] -

void luaL_pushresult (luaL_Buffer *B);
- -

-Finishes the use of buffer B leaving the final string on -the top of the stack. - - - - - -

luaL_pushresultsize

-[-?, +1, m] -

void luaL_pushresultsize (luaL_Buffer *B, size_t sz);
- -

-Equivalent to the sequence luaL_addsize, luaL_pushresult. - - - - - -

luaL_ref

-[-1, +0, m] -

int luaL_ref (lua_State *L, int t);
- -

-Creates and returns a reference, -in the table at index t, -for the object at the top of the stack (and pops the object). - - -

-A reference is a unique integer key. -As long as you do not manually add integer keys into table t, -luaL_ref ensures the uniqueness of the key it returns. -You can retrieve an object referred by reference r -by calling lua_rawgeti(L, t, r). -Function luaL_unref frees a reference and its associated object. - - -

-If the object at the top of the stack is nil, -luaL_ref returns the constant LUA_REFNIL. -The constant LUA_NOREF is guaranteed to be different -from any reference returned by luaL_ref. - - - - - -

luaL_Reg

-
typedef struct luaL_Reg {
-  const char *name;
-  lua_CFunction func;
-} luaL_Reg;
- -

-Type for arrays of functions to be registered by -luaL_setfuncs. -name is the function name and func is a pointer to -the function. -Any array of luaL_Reg must end with a sentinel entry -in which both name and func are NULL. - - - - - -

luaL_requiref

-[-0, +1, e] -

void luaL_requiref (lua_State *L, const char *modname,
-                    lua_CFunction openf, int glb);
- -

-If modname is not already present in package.loaded, -calls function openf with string modname as an argument -and sets the call result in package.loaded[modname], -as if that function has been called through require. - - -

-If glb is true, -also stores the module into global modname. - - -

-Leaves a copy of the module on the stack. - - - - - -

luaL_setfuncs

-[-nup, +0, m] -

void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);
- -

-Registers all functions in the array l -(see luaL_Reg) into the table on the top of the stack -(below optional upvalues, see next). - - -

-When nup is not zero, -all functions are created sharing nup upvalues, -which must be previously pushed on the stack -on top of the library table. -These values are popped from the stack after the registration. - - - - - -

luaL_setmetatable

-[-0, +0, –] -

void luaL_setmetatable (lua_State *L, const char *tname);
- -

-Sets the metatable of the object at the top of the stack -as the metatable associated with name tname -in the registry (see luaL_newmetatable). - - - - - -

luaL_Stream

-
typedef struct luaL_Stream {
-  FILE *f;
-  lua_CFunction closef;
-} luaL_Stream;
- -

-The standard representation for file handles, -which is used by the standard I/O library. - - -

-A file handle is implemented as a full userdata, -with a metatable called LUA_FILEHANDLE -(where LUA_FILEHANDLE is a macro with the actual metatable's name). -The metatable is created by the I/O library -(see luaL_newmetatable). - - -

-This userdata must start with the structure luaL_Stream; -it can contain other data after this initial structure. -Field f points to the corresponding C stream -(or it can be NULL to indicate an incompletely created handle). -Field closef points to a Lua function -that will be called to close the stream -when the handle is closed or collected; -this function receives the file handle as its sole argument and -must return either true (in case of success) -or nil plus an error message (in case of error). -Once Lua calls this field, -it changes the field value to NULL -to signal that the handle is closed. - - - - - -

luaL_testudata

-[-0, +0, m] -

void *luaL_testudata (lua_State *L, int arg, const char *tname);
- -

-This function works like luaL_checkudata, -except that, when the test fails, -it returns NULL instead of raising an error. - - - - - -

luaL_tolstring

-[-0, +1, e] -

const char *luaL_tolstring (lua_State *L, int idx, size_t *len);
- -

-Converts any Lua value at the given index to a C string -in a reasonable format. -The resulting string is pushed onto the stack and also -returned by the function. -If len is not NULL, -the function also sets *len with the string length. - - -

-If the value has a metatable with a __tostring field, -then luaL_tolstring calls the corresponding metamethod -with the value as argument, -and uses the result of the call as its result. - - - - - -

luaL_traceback

-[-0, +1, m] -

void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
-                     int level);
- -

-Creates and pushes a traceback of the stack L1. -If msg is not NULL it is appended -at the beginning of the traceback. -The level parameter tells at which level -to start the traceback. - - - - - -

luaL_typename

-[-0, +0, –] -

const char *luaL_typename (lua_State *L, int index);
- -

-Returns the name of the type of the value at the given index. - - - - - -

luaL_unref

-[-0, +0, –] -

void luaL_unref (lua_State *L, int t, int ref);
- -

-Releases reference ref from the table at index t -(see luaL_ref). -The entry is removed from the table, -so that the referred object can be collected. -The reference ref is also freed to be used again. - - -

-If ref is LUA_NOREF or LUA_REFNIL, -luaL_unref does nothing. - - - - - -

luaL_where

-[-0, +1, m] -

void luaL_where (lua_State *L, int lvl);
- -

-Pushes onto the stack a string identifying the current position -of the control at level lvl in the call stack. -Typically this string has the following format: - -

-     chunkname:currentline:
-

-Level 0 is the running function, -level 1 is the function that called the running function, -etc. - - -

-This function is used to build a prefix for error messages. - - - - - - - -

6 – Standard Libraries

- -

-The standard Lua libraries provide useful functions -that are implemented directly through the C API. -Some of these functions provide essential services to the language -(e.g., type and getmetatable); -others provide access to "outside" services (e.g., I/O); -and others could be implemented in Lua itself, -but are quite useful or have critical performance requirements that -deserve an implementation in C (e.g., table.sort). - - -

-All libraries are implemented through the official C API -and are provided as separate C modules. -Currently, Lua has the following standard libraries: - -

    - -
  • basic library (§6.1);
    • - -
  • coroutine library (§6.2);
    • - -
  • package library (§6.3);
    • - -
  • string manipulation (§6.4);
    • - -
  • basic UTF-8 support (§6.5);
    • - -
  • table manipulation (§6.6);
    • - -
  • mathematical functions (§6.7) (sin, log, etc.);
    • - -
  • input and output (§6.8);
    • - -
  • operating system facilities (§6.9);
    • - -
  • debug facilities (§6.10).
    • - -

-Except for the basic and the package libraries, -each library provides all its functions as fields of a global table -or as methods of its objects. - - -

-To have access to these libraries, -the C host program should call the luaL_openlibs function, -which opens all standard libraries. -Alternatively, -the host program can open them individually by using -luaL_requiref to call -luaopen_base (for the basic library), -luaopen_package (for the package library), -luaopen_coroutine (for the coroutine library), -luaopen_string (for the string library), -luaopen_utf8 (for the UTF8 library), -luaopen_table (for the table library), -luaopen_math (for the mathematical library), -luaopen_io (for the I/O library), -luaopen_os (for the operating system library), -and luaopen_debug (for the debug library). -These functions are declared in lualib.h. - - - -

6.1 – Basic Functions

- -

-The basic library provides core functions to Lua. -If you do not include this library in your application, -you should check carefully whether you need to provide -implementations for some of its facilities. - - -

-

assert (v [, message])

- - -

-Calls error if -the value of its argument v is false (i.e., nil or false); -otherwise, returns all its arguments. -In case of error, -message is the error object; -when absent, it defaults to "assertion failed!" - - - - -

-

collectgarbage ([opt [, arg]])

- - -

-This function is a generic interface to the garbage collector. -It performs different functions according to its first argument, opt: - -

    - -
  • "collect": -performs a full garbage-collection cycle. -This is the default option. -
    • - -
  • "stop": -stops automatic execution of the garbage collector. -The collector will run only when explicitly invoked, -until a call to restart it. -
    • - -
  • "restart": -restarts automatic execution of the garbage collector. -
    • - -
  • "count": -returns the total memory in use by Lua in Kbytes. -The value has a fractional part, -so that it multiplied by 1024 -gives the exact number of bytes in use by Lua -(except for overflows). -
    • - -
  • "step": -performs a garbage-collection step. -The step "size" is controlled by arg. -With a zero value, -the collector will perform one basic (indivisible) step. -For non-zero values, -the collector will perform as if that amount of memory -(in KBytes) had been allocated by Lua. -Returns true if the step finished a collection cycle. -
    • - -
  • "setpause": -sets arg as the new value for the pause of -the collector (see §2.5). -Returns the previous value for pause. -
    • - -
  • "setstepmul": -sets arg as the new value for the step multiplier of -the collector (see §2.5). -Returns the previous value for step. -
    • - -
  • "isrunning": -returns a boolean that tells whether the collector is running -(i.e., not stopped). -
    • - -
- - - -

-

dofile ([filename])

-Opens the named file and executes its contents as a Lua chunk. -When called without arguments, -dofile executes the contents of the standard input (stdin). -Returns all values returned by the chunk. -In case of errors, dofile propagates the error -to its caller (that is, dofile does not run in protected mode). - - - - -

-

error (message [, level])

-Terminates the last protected function called -and returns message as the error object. -Function error never returns. - - -

-Usually, error adds some information about the error position -at the beginning of the message, if the message is a string. -The level argument specifies how to get the error position. -With level 1 (the default), the error position is where the -error function was called. -Level 2 points the error to where the function -that called error was called; and so on. -Passing a level 0 avoids the addition of error position information -to the message. - - - - -

-

_G

-A global variable (not a function) that -holds the global environment (see §2.2). -Lua itself does not use this variable; -changing its value does not affect any environment, -nor vice versa. - - - - -

-

getmetatable (object)

- - -

-If object does not have a metatable, returns nil. -Otherwise, -if the object's metatable has a __metatable field, -returns the associated value. -Otherwise, returns the metatable of the given object. - - - - -

-

ipairs (t)

- - -

-Returns three values (an iterator function, the table t, and 0) -so that the construction - -

-     for i,v in ipairs(t) do body end
-

-will iterate over the key–value pairs -(1,t[1]), (2,t[2]), ..., -up to the first nil value. - - - - -

-

load (chunk [, chunkname [, mode [, env]]])

- - -

-Loads a chunk. - - -

-If chunk is a string, the chunk is this string. -If chunk is a function, -load calls it repeatedly to get the chunk pieces. -Each call to chunk must return a string that concatenates -with previous results. -A return of an empty string, nil, or no value signals the end of the chunk. - - -

-If there are no syntactic errors, -returns the compiled chunk as a function; -otherwise, returns nil plus the error message. - - -

-If the resulting function has upvalues, -the first upvalue is set to the value of env, -if that parameter is given, -or to the value of the global environment. -Other upvalues are initialized with nil. -(When you load a main chunk, -the resulting function will always have exactly one upvalue, -the _ENV variable (see §2.2). -However, -when you load a binary chunk created from a function (see string.dump), -the resulting function can have an arbitrary number of upvalues.) -All upvalues are fresh, that is, -they are not shared with any other function. - - -

-chunkname is used as the name of the chunk for error messages -and debug information (see §4.9). -When absent, -it defaults to chunk, if chunk is a string, -or to "=(load)" otherwise. - - -

-The string mode controls whether the chunk can be text or binary -(that is, a precompiled chunk). -It may be the string "b" (only binary chunks), -"t" (only text chunks), -or "bt" (both binary and text). -The default is "bt". - - -

-Lua does not check the consistency of binary chunks. -Maliciously crafted binary chunks can crash -the interpreter. - - - - -

-

loadfile ([filename [, mode [, env]]])

- - -

-Similar to load, -but gets the chunk from file filename -or from the standard input, -if no file name is given. - - - - -

-

next (table [, index])

- - -

-Allows a program to traverse all fields of a table. -Its first argument is a table and its second argument -is an index in this table. -next returns the next index of the table -and its associated value. -When called with nil as its second argument, -next returns an initial index -and its associated value. -When called with the last index, -or with nil in an empty table, -next returns nil. -If the second argument is absent, then it is interpreted as nil. -In particular, -you can use next(t) to check whether a table is empty. - - -

-The order in which the indices are enumerated is not specified, -even for numeric indices. -(To traverse a table in numerical order, -use a numerical for.) - - -

-The behavior of next is undefined if, -during the traversal, -you assign any value to a non-existent field in the table. -You may however modify existing fields. -In particular, you may clear existing fields. - - - - -

-

pairs (t)

- - -

-If t has a metamethod __pairs, -calls it with t as argument and returns the first three -results from the call. - - -

-Otherwise, -returns three values: the next function, the table t, and nil, -so that the construction - -

-     for k,v in pairs(t) do body end
-

-will iterate over all key–value pairs of table t. - - -

-See function next for the caveats of modifying -the table during its traversal. - - - - -

-

pcall (f [, arg1, ···])

- - -

-Calls function f with -the given arguments in protected mode. -This means that any error inside f is not propagated; -instead, pcall catches the error -and returns a status code. -Its first result is the status code (a boolean), -which is true if the call succeeds without errors. -In such case, pcall also returns all results from the call, -after this first result. -In case of any error, pcall returns false plus the error message. - - - - -

-

print (···)

-Receives any number of arguments -and prints their values to stdout, -using the tostring function to convert each argument to a string. -print is not intended for formatted output, -but only as a quick way to show a value, -for instance for debugging. -For complete control over the output, -use string.format and io.write. - - - - -

-

rawequal (v1, v2)

-Checks whether v1 is equal to v2, -without invoking the __eq metamethod. -Returns a boolean. - - - - -

-

rawget (table, index)

-Gets the real value of table[index], -without invoking the __index metamethod. -table must be a table; -index may be any value. - - - - -

-

rawlen (v)

-Returns the length of the object v, -which must be a table or a string, -without invoking the __len metamethod. -Returns an integer. - - - - -

-

rawset (table, index, value)

-Sets the real value of table[index] to value, -without invoking the __newindex metamethod. -table must be a table, -index any value different from nil and NaN, -and value any Lua value. - - -

-This function returns table. - - - - -

-

select (index, ···)

- - -

-If index is a number, -returns all arguments after argument number index; -a negative number indexes from the end (-1 is the last argument). -Otherwise, index must be the string "#", -and select returns the total number of extra arguments it received. - - - - -

-

setmetatable (table, metatable)

- - -

-Sets the metatable for the given table. -(To change the metatable of other types from Lua code, -you must use the debug library (§6.10).) -If metatable is nil, -removes the metatable of the given table. -If the original metatable has a __metatable field, -raises an error. - - -

-This function returns table. - - - - -

-

tonumber (e [, base])

- - -

-When called with no base, -tonumber tries to convert its argument to a number. -If the argument is already a number or -a string convertible to a number, -then tonumber returns this number; -otherwise, it returns nil. - - -

-The conversion of strings can result in integers or floats, -according to the lexical conventions of Lua (see §3.1). -(The string may have leading and trailing spaces and a sign.) - - -

-When called with base, -then e must be a string to be interpreted as -an integer numeral in that base. -The base may be any integer between 2 and 36, inclusive. -In bases above 10, the letter 'A' (in either upper or lower case) -represents 10, 'B' represents 11, and so forth, -with 'Z' representing 35. -If the string e is not a valid numeral in the given base, -the function returns nil. - - - - -

-

tostring (v)

-Receives a value of any type and -converts it to a string in a human-readable format. -(For complete control of how numbers are converted, -use string.format.) - - -

-If the metatable of v has a __tostring field, -then tostring calls the corresponding value -with v as argument, -and uses the result of the call as its result. - - - - -

-

type (v)

-Returns the type of its only argument, coded as a string. -The possible results of this function are -"nil" (a string, not the value nil), -"number", -"string", -"boolean", -"table", -"function", -"thread", -and "userdata". - - - - -

-

_VERSION

- - -

-A global variable (not a function) that -holds a string containing the running Lua version. -The current value of this variable is "Lua 5.3". - - - - -

-

xpcall (f, msgh [, arg1, ···])

- - -

-This function is similar to pcall, -except that it sets a new message handler msgh. - - - - - - - -

6.2 – Coroutine Manipulation

- -

-This library comprises the operations to manipulate coroutines, -which come inside the table coroutine. -See §2.6 for a general description of coroutines. - - -

-

coroutine.create (f)

- - -

-Creates a new coroutine, with body f. -f must be a function. -Returns this new coroutine, -an object with type "thread". - - - - -

-

coroutine.isyieldable ()

- - -

-Returns true when the running coroutine can yield. - - -

-A running coroutine is yieldable if it is not the main thread and -it is not inside a non-yieldable C function. - - - - -

-

coroutine.resume (co [, val1, ···])

- - -

-Starts or continues the execution of coroutine co. -The first time you resume a coroutine, -it starts running its body. -The values val1, ... are passed -as the arguments to the body function. -If the coroutine has yielded, -resume restarts it; -the values val1, ... are passed -as the results from the yield. - - -

-If the coroutine runs without any errors, -resume returns true plus any values passed to yield -(when the coroutine yields) or any values returned by the body function -(when the coroutine terminates). -If there is any error, -resume returns false plus the error message. - - - - -

-

coroutine.running ()

- - -

-Returns the running coroutine plus a boolean, -true when the running coroutine is the main one. - - - - -

-

coroutine.status (co)

- - -

-Returns the status of coroutine co, as a string: -"running", -if the coroutine is running (that is, it called status); -"suspended", if the coroutine is suspended in a call to yield, -or if it has not started running yet; -"normal" if the coroutine is active but not running -(that is, it has resumed another coroutine); -and "dead" if the coroutine has finished its body function, -or if it has stopped with an error. - - - - -

-

coroutine.wrap (f)

- - -

-Creates a new coroutine, with body f. -f must be a function. -Returns a function that resumes the coroutine each time it is called. -Any arguments passed to the function behave as the -extra arguments to resume. -Returns the same values returned by resume, -except the first boolean. -In case of error, propagates the error. - - - - -

-

coroutine.yield (···)

- - -

-Suspends the execution of the calling coroutine. -Any arguments to yield are passed as extra results to resume. - - - - - - - -

6.3 – Modules

- -

-The package library provides basic -facilities for loading modules in Lua. -It exports one function directly in the global environment: -require. -Everything else is exported in a table package. - - -

-

require (modname)

- - -

-Loads the given module. -The function starts by looking into the package.loaded table -to determine whether modname is already loaded. -If it is, then require returns the value stored -at package.loaded[modname]. -Otherwise, it tries to find a loader for the module. - - -

-To find a loader, -require is guided by the package.searchers sequence. -By changing this sequence, -we can change how require looks for a module. -The following explanation is based on the default configuration -for package.searchers. - - -

-First require queries package.preload[modname]. -If it has a value, -this value (which must be a function) is the loader. -Otherwise require searches for a Lua loader using the -path stored in package.path. -If that also fails, it searches for a C loader using the -path stored in package.cpath. -If that also fails, -it tries an all-in-one loader (see package.searchers). - - -

-Once a loader is found, -require calls the loader with two arguments: -modname and an extra value dependent on how it got the loader. -(If the loader came from a file, -this extra value is the file name.) -If the loader returns any non-nil value, -require assigns the returned value to package.loaded[modname]. -If the loader does not return a non-nil value and -has not assigned any value to package.loaded[modname], -then require assigns true to this entry. -In any case, require returns the -final value of package.loaded[modname]. - - -

-If there is any error loading or running the module, -or if it cannot find any loader for the module, -then require raises an error. - - - - -

-

package.config

- - -

-A string describing some compile-time configurations for packages. -This string is a sequence of lines: - -

    - -
  • The first line is the directory separator string. -Default is '\' for Windows and '/' for all other systems.
    • - -
  • The second line is the character that separates templates in a path. -Default is ';'.
    • - -
  • The third line is the string that marks the -substitution points in a template. -Default is '?'.
    • - -
  • The fourth line is a string that, in a path in Windows, -is replaced by the executable's directory. -Default is '!'.
    • - -
  • The fifth line is a mark to ignore all text after it -when building the luaopen_ function name. -Default is '-'.
    • - -
- - - -

-

package.cpath

- - -

-The path used by require to search for a C loader. - - -

-Lua initializes the C path package.cpath in the same way -it initializes the Lua path package.path, -using the environment variable LUA_CPATH_5_3, -or the environment variable LUA_CPATH, -or a default path defined in luaconf.h. - - - - -

-

package.loaded

- - -

-A table used by require to control which -modules are already loaded. -When you require a module modname and -package.loaded[modname] is not false, -require simply returns the value stored there. - - -

-This variable is only a reference to the real table; -assignments to this variable do not change the -table used by require. - - - - -

-

package.loadlib (libname, funcname)

- - -

-Dynamically links the host program with the C library libname. - - -

-If funcname is "*", -then it only links with the library, -making the symbols exported by the library -available to other dynamically linked libraries. -Otherwise, -it looks for a function funcname inside the library -and returns this function as a C function. -So, funcname must follow the lua_CFunction prototype -(see lua_CFunction). - - -

-This is a low-level function. -It completely bypasses the package and module system. -Unlike require, -it does not perform any path searching and -does not automatically adds extensions. -libname must be the complete file name of the C library, -including if necessary a path and an extension. -funcname must be the exact name exported by the C library -(which may depend on the C compiler and linker used). - - -

-This function is not supported by Standard C. -As such, it is only available on some platforms -(Windows, Linux, Mac OS X, Solaris, BSD, -plus other Unix systems that support the dlfcn standard). - - - - -

-

package.path

- - -

-The path used by require to search for a Lua loader. - - -

-At start-up, Lua initializes this variable with -the value of the environment variable LUA_PATH_5_3 or -the environment variable LUA_PATH or -with a default path defined in luaconf.h, -if those environment variables are not defined. -Any ";;" in the value of the environment variable -is replaced by the default path. - - - - -

-

package.preload

- - -

-A table to store loaders for specific modules -(see require). - - -

-This variable is only a reference to the real table; -assignments to this variable do not change the -table used by require. - - - - -

-

package.searchers

- - -

-A table used by require to control how to load modules. - - -

-Each entry in this table is a searcher function. -When looking for a module, -require calls each of these searchers in ascending order, -with the module name (the argument given to require) as its -sole parameter. -The function can return another function (the module loader) -plus an extra value that will be passed to that loader, -or a string explaining why it did not find that module -(or nil if it has nothing to say). - - -

-Lua initializes this table with four searcher functions. - - -

-The first searcher simply looks for a loader in the -package.preload table. - - -

-The second searcher looks for a loader as a Lua library, -using the path stored at package.path. -The search is done as described in function package.searchpath. - - -

-The third searcher looks for a loader as a C library, -using the path given by the variable package.cpath. -Again, -the search is done as described in function package.searchpath. -For instance, -if the C path is the string - -

-     "./?.so;./?.dll;/usr/local/?/init.so"
-

-the searcher for module foo -will try to open the files ./foo.so, ./foo.dll, -and /usr/local/foo/init.so, in that order. -Once it finds a C library, -this searcher first uses a dynamic link facility to link the -application with the library. -Then it tries to find a C function inside the library to -be used as the loader. -The name of this C function is the string "luaopen_" -concatenated with a copy of the module name where each dot -is replaced by an underscore. -Moreover, if the module name has a hyphen, -its suffix after (and including) the first hyphen is removed. -For instance, if the module name is a.b.c-v2.1, -the function name will be luaopen_a_b_c. - - -

-The fourth searcher tries an all-in-one loader. -It searches the C path for a library for -the root name of the given module. -For instance, when requiring a.b.c, -it will search for a C library for a. -If found, it looks into it for an open function for -the submodule; -in our example, that would be luaopen_a_b_c. -With this facility, a package can pack several C submodules -into one single library, -with each submodule keeping its original open function. - - -

-All searchers except the first one (preload) return as the extra value -the file name where the module was found, -as returned by package.searchpath. -The first searcher returns no extra value. - - - - -

-

package.searchpath (name, path [, sep [, rep]])

- - -

-Searches for the given name in the given path. - - -

-A path is a string containing a sequence of -templates separated by semicolons. -For each template, -the function replaces each interrogation mark (if any) -in the template with a copy of name -wherein all occurrences of sep -(a dot, by default) -were replaced by rep -(the system's directory separator, by default), -and then tries to open the resulting file name. - - -

-For instance, if the path is the string - -

-     "./?.lua;./?.lc;/usr/local/?/init.lua"
-

-the search for the name foo.a -will try to open the files -./foo/a.lua, ./foo/a.lc, and -/usr/local/foo/a/init.lua, in that order. - - -

-Returns the resulting name of the first file that it can -open in read mode (after closing the file), -or nil plus an error message if none succeeds. -(This error message lists all file names it tried to open.) - - - - - - - -

6.4 – String Manipulation

- -

-This library provides generic functions for string manipulation, -such as finding and extracting substrings, and pattern matching. -When indexing a string in Lua, the first character is at position 1 -(not at 0, as in C). -Indices are allowed to be negative and are interpreted as indexing backwards, -from the end of the string. -Thus, the last character is at position -1, and so on. - - -

-The string library provides all its functions inside the table -string. -It also sets a metatable for strings -where the __index field points to the string table. -Therefore, you can use the string functions in object-oriented style. -For instance, string.byte(s,i) -can be written as s:byte(i). - - -

-The string library assumes one-byte character encodings. - - -

-

string.byte (s [, i [, j]])

-Returns the internal numeric codes of the characters s[i], -s[i+1], ..., s[j]. -The default value for i is 1; -the default value for j is i. -These indices are corrected -following the same rules of function string.sub. - - -

-Numeric codes are not necessarily portable across platforms. - - - - -

-

string.char (···)

-Receives zero or more integers. -Returns a string with length equal to the number of arguments, -in which each character has the internal numeric code equal -to its corresponding argument. - - -

-Numeric codes are not necessarily portable across platforms. - - - - -

-

string.dump (function [, strip])

- - -

-Returns a string containing a binary representation -(a binary chunk) -of the given function, -so that a later load on this string returns -a copy of the function (but with new upvalues). -If strip is a true value, -the binary representation may not include all debug information -about the function, -to save space. - - -

-Functions with upvalues have only their number of upvalues saved. -When (re)loaded, -those upvalues receive fresh instances containing nil. -(You can use the debug library to serialize -and reload the upvalues of a function -in a way adequate to your needs.) - - - - -

-

string.find (s, pattern [, init [, plain]])

- - -

-Looks for the first match of -pattern (see §6.4.1) in the string s. -If it finds a match, then find returns the indices of s -where this occurrence starts and ends; -otherwise, it returns nil. -A third, optional numeric argument init specifies -where to start the search; -its default value is 1 and can be negative. -A value of true as a fourth, optional argument plain -turns off the pattern matching facilities, -so the function does a plain "find substring" operation, -with no characters in pattern being considered magic. -Note that if plain is given, then init must be given as well. - - -

-If the pattern has captures, -then in a successful match -the captured values are also returned, -after the two indices. - - - - -

-

string.format (formatstring, ···)

- - -

-Returns a formatted version of its variable number of arguments -following the description given in its first argument (which must be a string). -The format string follows the same rules as the ISO C function sprintf. -The only differences are that the options/modifiers -*, h, L, l, n, -and p are not supported -and that there is an extra option, q. - - -

-The q option formats a string between double quotes, -using escape sequences when necessary to ensure that -it can safely be read back by the Lua interpreter. -For instance, the call - -

-     string.format('%q', 'a string with "quotes" and \n new line')
-

-may produce the string: - -

-     "a string with \"quotes\" and \
-      new line"
-
- -

-Options -A, a, E, e, f, -G, and g all expect a number as argument. -Options c, d, -i, o, u, X, and x -expect an integer. -When Lua is compiled with a C89 compiler, -options A and a (hexadecimal floats) -do not support any modifier (flags, width, length). - - -

-Option s expects a string; -if its argument is not a string, -it is converted to one following the same rules of tostring. -If the option has any modifier (flags, width, length), -the string argument should not contain embedded zeros. - - - - -

-

string.gmatch (s, pattern)

-Returns an iterator function that, -each time it is called, -returns the next captures from pattern (see §6.4.1) -over the string s. -If pattern specifies no captures, -then the whole match is produced in each call. - - -

-As an example, the following loop -will iterate over all the words from string s, -printing one per line: - -

-     s = "hello world from Lua"
-     for w in string.gmatch(s, "%a+") do
-       print(w)
-     end
-

-The next example collects all pairs key=value from the -given string into a table: - -

-     t = {}
-     s = "from=world, to=Lua"
-     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
-       t[k] = v
-     end
-
- -

-For this function, a caret '^' at the start of a pattern does not -work as an anchor, as this would prevent the iteration. - - - - -

-

string.gsub (s, pattern, repl [, n])

-Returns a copy of s -in which all (or the first n, if given) -occurrences of the pattern (see §6.4.1) have been -replaced by a replacement string specified by repl, -which can be a string, a table, or a function. -gsub also returns, as its second value, -the total number of matches that occurred. -The name gsub comes from Global SUBstitution. - - -

-If repl is a string, then its value is used for replacement. -The character % works as an escape character: -any sequence in repl of the form %d, -with d between 1 and 9, -stands for the value of the d-th captured substring. -The sequence %0 stands for the whole match. -The sequence %% stands for a single %. - - -

-If repl is a table, then the table is queried for every match, -using the first capture as the key. - - -

-If repl is a function, then this function is called every time a -match occurs, with all captured substrings passed as arguments, -in order. - - -

-In any case, -if the pattern specifies no captures, -then it behaves as if the whole pattern was inside a capture. - - -

-If the value returned by the table query or by the function call -is a string or a number, -then it is used as the replacement string; -otherwise, if it is false or nil, -then there is no replacement -(that is, the original match is kept in the string). - - -

-Here are some examples: - -

-     x = string.gsub("hello world", "(%w+)", "%1 %1")
-     --> x="hello hello world world"
-     
-     x = string.gsub("hello world", "%w+", "%0 %0", 1)
-     --> x="hello hello world"
-     
-     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
-     --> x="world hello Lua from"
-     
-     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
-     --> x="home = /home/roberto, user = roberto"
-     
-     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
-           return load(s)()
-         end)
-     --> x="4+5 = 9"
-     
-     local t = {name="lua", version="5.3"}
-     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
-     --> x="lua-5.3.tar.gz"
-
- - - -

-

string.len (s)

-Receives a string and returns its length. -The empty string "" has length 0. -Embedded zeros are counted, -so "a\000bc\000" has length 5. - - - - -

-

string.lower (s)

-Receives a string and returns a copy of this string with all -uppercase letters changed to lowercase. -All other characters are left unchanged. -The definition of what an uppercase letter is depends on the current locale. - - - - -

-

string.match (s, pattern [, init])

-Looks for the first match of -pattern (see §6.4.1) in the string s. -If it finds one, then match returns -the captures from the pattern; -otherwise it returns nil. -If pattern specifies no captures, -then the whole match is returned. -A third, optional numeric argument init specifies -where to start the search; -its default value is 1 and can be negative. - - - - -

-

string.pack (fmt, v1, v2, ···)

- - -

-Returns a binary string containing the values v1, v2, etc. -packed (that is, serialized in binary form) -according to the format string fmt (see §6.4.2). - - - - -

-

string.packsize (fmt)

- - -

-Returns the size of a string resulting from string.pack -with the given format. -The format string cannot have the variable-length options -'s' or 'z' (see §6.4.2). - - - - -

-

string.rep (s, n [, sep])

-Returns a string that is the concatenation of n copies of -the string s separated by the string sep. -The default value for sep is the empty string -(that is, no separator). -Returns the empty string if n is not positive. - - -

-(Note that it is very easy to exhaust the memory of your machine -with a single call to this function.) - - - - -

-

string.reverse (s)

-Returns a string that is the string s reversed. - - - - -

-

string.sub (s, i [, j])

-Returns the substring of s that -starts at i and continues until j; -i and j can be negative. -If j is absent, then it is assumed to be equal to -1 -(which is the same as the string length). -In particular, -the call string.sub(s,1,j) returns a prefix of s -with length j, -and string.sub(s, -i) (for a positive i) -returns a suffix of s -with length i. - - -

-If, after the translation of negative indices, -i is less than 1, -it is corrected to 1. -If j is greater than the string length, -it is corrected to that length. -If, after these corrections, -i is greater than j, -the function returns the empty string. - - - - -

-

string.unpack (fmt, s [, pos])

- - -

-Returns the values packed in string s (see string.pack) -according to the format string fmt (see §6.4.2). -An optional pos marks where -to start reading in s (default is 1). -After the read values, -this function also returns the index of the first unread byte in s. - - - - -

-

string.upper (s)

-Receives a string and returns a copy of this string with all -lowercase letters changed to uppercase. -All other characters are left unchanged. -The definition of what a lowercase letter is depends on the current locale. - - - - - -

6.4.1 – Patterns

- -

-Patterns in Lua are described by regular strings, -which are interpreted as patterns by the pattern-matching functions -string.find, -string.gmatch, -string.gsub, -and string.match. -This section describes the syntax and the meaning -(that is, what they match) of these strings. - - - -

Character Class:

-A character class is used to represent a set of characters. -The following combinations are allowed in describing a character class: - -

    - -
  • x: -(where x is not one of the magic characters -^$()%.[]*+-?) -represents the character x itself. -
    • - -
  • .: (a dot) represents all characters.
    • - -
  • %a: represents all letters.
    • - -
  • %c: represents all control characters.
    • - -
  • %d: represents all digits.
    • - -
  • %g: represents all printable characters except space.
    • - -
  • %l: represents all lowercase letters.
    • - -
  • %p: represents all punctuation characters.
    • - -
  • %s: represents all space characters.
    • - -
  • %u: represents all uppercase letters.
    • - -
  • %w: represents all alphanumeric characters.
    • - -
  • %x: represents all hexadecimal digits.
    • - -
  • %x: (where x is any non-alphanumeric character) -represents the character x. -This is the standard way to escape the magic characters. -Any non-alphanumeric character -(including all punctuation characters, even the non-magical) -can be preceded by a '%' -when used to represent itself in a pattern. -
    • - -
  • [set]: -represents the class which is the union of all -characters in set. -A range of characters can be specified by -separating the end characters of the range, -in ascending order, with a '-'. -All classes %x described above can also be used as -components in set. -All other characters in set represent themselves. -For example, [%w_] (or [_%w]) -represents all alphanumeric characters plus the underscore, -[0-7] represents the octal digits, -and [0-7%l%-] represents the octal digits plus -the lowercase letters plus the '-' character. - - -

    -You can put a closing square bracket in a set -by positioning it as the first character in the set. -You can put a hyphen in a set -by positioning it as the first or the last character in the set. -(You can also use an escape for both cases.) - - -

    -The interaction between ranges and classes is not defined. -Therefore, patterns like [%a-z] or [a-%%] -have no meaning. -

    • - -
  • [^set]: -represents the complement of set, -where set is interpreted as above. -
    • - -

-For all classes represented by single letters (%a, %c, etc.), -the corresponding uppercase letter represents the complement of the class. -For instance, %S represents all non-space characters. - - -

-The definitions of letter, space, and other character groups -depend on the current locale. -In particular, the class [a-z] may not be equivalent to %l. - - - - - -

Pattern Item:

-A pattern item can be - -

    - -
  • -a single character class, -which matches any single character in the class; -
    • - -
  • -a single character class followed by '*', -which matches zero or more repetitions of characters in the class. -These repetition items will always match the longest possible sequence; -
    • - -
  • -a single character class followed by '+', -which matches one or more repetitions of characters in the class. -These repetition items will always match the longest possible sequence; -
    • - -
  • -a single character class followed by '-', -which also matches zero or more repetitions of characters in the class. -Unlike '*', -these repetition items will always match the shortest possible sequence; -
    • - -
  • -a single character class followed by '?', -which matches zero or one occurrence of a character in the class. -It always matches one occurrence if possible; -
    • - -
  • -%n, for n between 1 and 9; -such item matches a substring equal to the n-th captured string -(see below); -
    • - -
  • -%bxy, where x and y are two distinct characters; -such item matches strings that start with x, end with y, -and where the x and y are balanced. -This means that, if one reads the string from left to right, -counting +1 for an x and -1 for a y, -the ending y is the first y where the count reaches 0. -For instance, the item %b() matches expressions with -balanced parentheses. -
    • - -
  • -%f[set], a frontier pattern; -such item matches an empty string at any position such that -the next character belongs to set -and the previous character does not belong to set. -The set set is interpreted as previously described. -The beginning and the end of the subject are handled as if -they were the character '\0'. -
    • - -
- - - - -

Pattern:

-A pattern is a sequence of pattern items. -A caret '^' at the beginning of a pattern anchors the match at the -beginning of the subject string. -A '$' at the end of a pattern anchors the match at the -end of the subject string. -At other positions, -'^' and '$' have no special meaning and represent themselves. - - - - - -

Captures:

-A pattern can contain sub-patterns enclosed in parentheses; -they describe captures. -When a match succeeds, the substrings of the subject string -that match captures are stored (captured) for future use. -Captures are numbered according to their left parentheses. -For instance, in the pattern "(a*(.)%w(%s*))", -the part of the string matching "a*(.)%w(%s*)" is -stored as the first capture (and therefore has number 1); -the character matching "." is captured with number 2, -and the part matching "%s*" has number 3. - - -

-As a special case, the empty capture () captures -the current string position (a number). -For instance, if we apply the pattern "()aa()" on the -string "flaaap", there will be two captures: 3 and 5. - - - - - - - -

6.4.2 – Format Strings for Pack and Unpack

- -

-The first argument to string.pack, -string.packsize, and string.unpack -is a format string, -which describes the layout of the structure being created or read. - - -

-A format string is a sequence of conversion options. -The conversion options are as follows: - -

    -
  • <: sets little endian
    • -
  • >: sets big endian
    • -
  • =: sets native endian
    • -
  • ![n]: sets maximum alignment to n -(default is native alignment)
    • -
  • b: a signed byte (char)
    • -
  • B: an unsigned byte (char)
    • -
  • h: a signed short (native size)
    • -
  • H: an unsigned short (native size)
    • -
  • l: a signed long (native size)
    • -
  • L: an unsigned long (native size)
    • -
  • j: a lua_Integer
    • -
  • J: a lua_Unsigned
    • -
  • T: a size_t (native size)
    • -
  • i[n]: a signed int with n bytes -(default is native size)
    • -
  • I[n]: an unsigned int with n bytes -(default is native size)
    • -
  • f: a float (native size)
    • -
  • d: a double (native size)
    • -
  • n: a lua_Number
    • -
  • cn: a fixed-sized string with n bytes
    • -
  • z: a zero-terminated string
    • -
  • s[n]: a string preceded by its length -coded as an unsigned integer with n bytes -(default is a size_t)
    • -
  • x: one byte of padding
    • -
  • Xop: an empty item that aligns -according to option op -(which is otherwise ignored)
    • -
  • ' ': (empty space) ignored
    • -

-(A "[n]" means an optional integral numeral.) -Except for padding, spaces, and configurations -(options "xX <=>!"), -each option corresponds to an argument (in string.pack) -or a result (in string.unpack). - - -

-For options "!n", "sn", "in", and "In", -n can be any integer between 1 and 16. -All integral options check overflows; -string.pack checks whether the given value fits in the given size; -string.unpack checks whether the read value fits in a Lua integer. - - -

-Any format string starts as if prefixed by "!1=", -that is, -with maximum alignment of 1 (no alignment) -and native endianness. - - -

-Alignment works as follows: -For each option, -the format gets extra padding until the data starts -at an offset that is a multiple of the minimum between the -option size and the maximum alignment; -this minimum must be a power of 2. -Options "c" and "z" are not aligned; -option "s" follows the alignment of its starting integer. - - -

-All padding is filled with zeros by string.pack -(and ignored by string.unpack). - - - - - - - -

6.5 – UTF-8 Support

- -

-This library provides basic support for UTF-8 encoding. -It provides all its functions inside the table utf8. -This library does not provide any support for Unicode other -than the handling of the encoding. -Any operation that needs the meaning of a character, -such as character classification, is outside its scope. - - -

-Unless stated otherwise, -all functions that expect a byte position as a parameter -assume that the given position is either the start of a byte sequence -or one plus the length of the subject string. -As in the string library, -negative indices count from the end of the string. - - -

-

utf8.char (···)

-Receives zero or more integers, -converts each one to its corresponding UTF-8 byte sequence -and returns a string with the concatenation of all these sequences. - - - - -

-

utf8.charpattern

-The pattern (a string, not a function) "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" -(see §6.4.1), -which matches exactly one UTF-8 byte sequence, -assuming that the subject is a valid UTF-8 string. - - - - -

-

utf8.codes (s)

- - -

-Returns values so that the construction - -

-     for p, c in utf8.codes(s) do body end
-

-will iterate over all characters in string s, -with p being the position (in bytes) and c the code point -of each character. -It raises an error if it meets any invalid byte sequence. - - - - -

-

utf8.codepoint (s [, i [, j]])

-Returns the codepoints (as integers) from all characters in s -that start between byte position i and j (both included). -The default for i is 1 and for j is i. -It raises an error if it meets any invalid byte sequence. - - - - -

-

utf8.len (s [, i [, j]])

-Returns the number of UTF-8 characters in string s -that start between positions i and j (both inclusive). -The default for i is 1 and for j is -1. -If it finds any invalid byte sequence, -returns a false value plus the position of the first invalid byte. - - - - -

-

utf8.offset (s, n [, i])

-Returns the position (in bytes) where the encoding of the -n-th character of s -(counting from position i) starts. -A negative n gets characters before position i. -The default for i is 1 when n is non-negative -and #s + 1 otherwise, -so that utf8.offset(s, -n) gets the offset of the -n-th character from the end of the string. -If the specified character is neither in the subject -nor right after its end, -the function returns nil. - - -

-As a special case, -when n is 0 the function returns the start of the encoding -of the character that contains the i-th byte of s. - - -

-This function assumes that s is a valid UTF-8 string. - - - - - - - -

6.6 – Table Manipulation

- -

-This library provides generic functions for table manipulation. -It provides all its functions inside the table table. - - -

-Remember that, whenever an operation needs the length of a table, -all caveats about the length operator apply (see §3.4.7). -All functions ignore non-numeric keys -in the tables given as arguments. - - -

-

table.concat (list [, sep [, i [, j]]])

- - -

-Given a list where all elements are strings or numbers, -returns the string list[i]..sep..list[i+1] ··· sep..list[j]. -The default value for sep is the empty string, -the default for i is 1, -and the default for j is #list. -If i is greater than j, returns the empty string. - - - - -

-

table.insert (list, [pos,] value)

- - -

-Inserts element value at position pos in list, -shifting up the elements -list[pos], list[pos+1], ···, list[#list]. -The default value for pos is #list+1, -so that a call table.insert(t,x) inserts x at the end -of list t. - - - - -

-

table.move (a1, f, e, t [,a2])

- - -

-Moves elements from table a1 to table a2, -performing the equivalent to the following -multiple assignment: -a2[t],··· = a1[f],···,a1[e]. -The default for a2 is a1. -The destination range can overlap with the source range. -The number of elements to be moved must fit in a Lua integer. - - -

-Returns the destination table a2. - - - - -

-

table.pack (···)

- - -

-Returns a new table with all arguments stored into keys 1, 2, etc. -and with a field "n" with the total number of arguments. -Note that the resulting table may not be a sequence. - - - - -

-

table.remove (list [, pos])

- - -

-Removes from list the element at position pos, -returning the value of the removed element. -When pos is an integer between 1 and #list, -it shifts down the elements -list[pos+1], list[pos+2], ···, list[#list] -and erases element list[#list]; -The index pos can also be 0 when #list is 0, -or #list + 1; -in those cases, the function erases the element list[pos]. - - -

-The default value for pos is #list, -so that a call table.remove(l) removes the last element -of list l. - - - - -

-

table.sort (list [, comp])

- - -

-Sorts list elements in a given order, in-place, -from list[1] to list[#list]. -If comp is given, -then it must be a function that receives two list elements -and returns true when the first element must come -before the second in the final order -(so that, after the sort, -i < j implies not comp(list[j],list[i])). -If comp is not given, -then the standard Lua operator < is used instead. - - -

-Note that the comp function must define -a strict partial order over the elements in the list; -that is, it must be asymmetric and transitive. -Otherwise, no valid sort may be possible. - - -

-The sort algorithm is not stable: -elements considered equal by the given order -may have their relative positions changed by the sort. - - - - -

-

table.unpack (list [, i [, j]])

- - -

-Returns the elements from the given list. -This function is equivalent to - -

-     return list[i], list[i+1], ···, list[j]
-

-By default, i is 1 and j is #list. - - - - - - - -

6.7 – Mathematical Functions

- -

-This library provides basic mathematical functions. -It provides all its functions and constants inside the table math. -Functions with the annotation "integer/float" give -integer results for integer arguments -and float results for float (or mixed) arguments. -Rounding functions -(math.ceil, math.floor, and math.modf) -return an integer when the result fits in the range of an integer, -or a float otherwise. - - -

-

math.abs (x)

- - -

-Returns the absolute value of x. (integer/float) - - - - -

-

math.acos (x)

- - -

-Returns the arc cosine of x (in radians). - - - - -

-

math.asin (x)

- - -

-Returns the arc sine of x (in radians). - - - - -

-

math.atan (y [, x])

- - -

- -Returns the arc tangent of y/x (in radians), -but uses the signs of both arguments to find the -quadrant of the result. -(It also handles correctly the case of x being zero.) - - -

-The default value for x is 1, -so that the call math.atan(y) -returns the arc tangent of y. - - - - -

-

math.ceil (x)

- - -

-Returns the smallest integral value larger than or equal to x. - - - - -

-

math.cos (x)

- - -

-Returns the cosine of x (assumed to be in radians). - - - - -

-

math.deg (x)

- - -

-Converts the angle x from radians to degrees. - - - - -

-

math.exp (x)

- - -

-Returns the value ex -(where e is the base of natural logarithms). - - - - -

-

math.floor (x)

- - -

-Returns the largest integral value smaller than or equal to x. - - - - -

-

math.fmod (x, y)

- - -

-Returns the remainder of the division of x by y -that rounds the quotient towards zero. (integer/float) - - - - -

-

math.huge

- - -

-The float value HUGE_VAL, -a value larger than any other numeric value. - - - - -

-

math.log (x [, base])

- - -

-Returns the logarithm of x in the given base. -The default for base is e -(so that the function returns the natural logarithm of x). - - - - -

-

math.max (x, ···)

- - -

-Returns the argument with the maximum value, -according to the Lua operator <. (integer/float) - - - - -

-

math.maxinteger

-An integer with the maximum value for an integer. - - - - -

-

math.min (x, ···)

- - -

-Returns the argument with the minimum value, -according to the Lua operator <. (integer/float) - - - - -

-

math.mininteger

-An integer with the minimum value for an integer. - - - - -

-

math.modf (x)

- - -

-Returns the integral part of x and the fractional part of x. -Its second result is always a float. - - - - -

-

math.pi

- - -

-The value of π. - - - - -

-

math.rad (x)

- - -

-Converts the angle x from degrees to radians. - - - - -

-

math.random ([m [, n]])

- - -

-When called without arguments, -returns a pseudo-random float with uniform distribution -in the range [0,1). -When called with two integers m and n, -math.random returns a pseudo-random integer -with uniform distribution in the range [m, n]. -(The value n-m cannot be negative and must fit in a Lua integer.) -The call math.random(n) is equivalent to math.random(1,n). - - -

-This function is an interface to the underling -pseudo-random generator function provided by C. - - - - -

-

math.randomseed (x)

- - -

-Sets x as the "seed" -for the pseudo-random generator: -equal seeds produce equal sequences of numbers. - - - - -

-

math.sin (x)

- - -

-Returns the sine of x (assumed to be in radians). - - - - -

-

math.sqrt (x)

- - -

-Returns the square root of x. -(You can also use the expression x^0.5 to compute this value.) - - - - -

-

math.tan (x)

- - -

-Returns the tangent of x (assumed to be in radians). - - - - -

-

math.tointeger (x)

- - -

-If the value x is convertible to an integer, -returns that integer. -Otherwise, returns nil. - - - - -

-

math.type (x)

- - -

-Returns "integer" if x is an integer, -"float" if it is a float, -or nil if x is not a number. - - - - -

-

math.ult (m, n)

- - -

-Returns a boolean, -true if and only if integer m is below integer n when -they are compared as unsigned integers. - - - - - - - -

6.8 – Input and Output Facilities

- -

-The I/O library provides two different styles for file manipulation. -The first one uses implicit file handles; -that is, there are operations to set a default input file and a -default output file, -and all input/output operations are over these default files. -The second style uses explicit file handles. - - -

-When using implicit file handles, -all operations are supplied by table io. -When using explicit file handles, -the operation io.open returns a file handle -and then all operations are supplied as methods of the file handle. - - -

-The table io also provides -three predefined file handles with their usual meanings from C: -io.stdin, io.stdout, and io.stderr. -The I/O library never closes these files. - - -

-Unless otherwise stated, -all I/O functions return nil on failure -(plus an error message as a second result and -a system-dependent error code as a third result) -and some value different from nil on success. -In non-POSIX systems, -the computation of the error message and error code -in case of errors -may be not thread safe, -because they rely on the global C variable errno. - - -

-

io.close ([file])

- - -

-Equivalent to file:close(). -Without a file, closes the default output file. - - - - -

-

io.flush ()

- - -

-Equivalent to io.output():flush(). - - - - -

-

io.input ([file])

- - -

-When called with a file name, it opens the named file (in text mode), -and sets its handle as the default input file. -When called with a file handle, -it simply sets this file handle as the default input file. -When called without arguments, -it returns the current default input file. - - -

-In case of errors this function raises the error, -instead of returning an error code. - - - - -

-

io.lines ([filename, ···])

- - -

-Opens the given file name in read mode -and returns an iterator function that -works like file:lines(···) over the opened file. -When the iterator function detects the end of file, -it returns no values (to finish the loop) and automatically closes the file. - - -

-The call io.lines() (with no file name) is equivalent -to io.input():lines("*l"); -that is, it iterates over the lines of the default input file. -In this case, the iterator does not close the file when the loop ends. - - -

-In case of errors this function raises the error, -instead of returning an error code. - - - - -

-

io.open (filename [, mode])

- - -

-This function opens a file, -in the mode specified in the string mode. -In case of success, -it returns a new file handle. - - -

-The mode string can be any of the following: - -

    -
  • "r": read mode (the default);
    • -
  • "w": write mode;
    • -
  • "a": append mode;
    • -
  • "r+": update mode, all previous data is preserved;
    • -
  • "w+": update mode, all previous data is erased;
    • -
  • "a+": append update mode, previous data is preserved, - writing is only allowed at the end of file.
    • -

-The mode string can also have a 'b' at the end, -which is needed in some systems to open the file in binary mode. - - - - -

-

io.output ([file])

- - -

-Similar to io.input, but operates over the default output file. - - - - -

-

io.popen (prog [, mode])

- - -

-This function is system dependent and is not available -on all platforms. - - -

-Starts program prog in a separated process and returns -a file handle that you can use to read data from this program -(if mode is "r", the default) -or to write data to this program -(if mode is "w"). - - - - -

-

io.read (···)

- - -

-Equivalent to io.input():read(···). - - - - -

-

io.tmpfile ()

- - -

-In case of success, -returns a handle for a temporary file. -This file is opened in update mode -and it is automatically removed when the program ends. - - - - -

-

io.type (obj)

- - -

-Checks whether obj is a valid file handle. -Returns the string "file" if obj is an open file handle, -"closed file" if obj is a closed file handle, -or nil if obj is not a file handle. - - - - -

-

io.write (···)

- - -

-Equivalent to io.output():write(···). - - - - -

-

file:close ()

- - -

-Closes file. -Note that files are automatically closed when -their handles are garbage collected, -but that takes an unpredictable amount of time to happen. - - -

-When closing a file handle created with io.popen, -file:close returns the same values -returned by os.execute. - - - - -

-

file:flush ()

- - -

-Saves any written data to file. - - - - -

-

file:lines (···)

- - -

-Returns an iterator function that, -each time it is called, -reads the file according to the given formats. -When no format is given, -uses "l" as a default. -As an example, the construction - -

-     for c in file:lines(1) do body end
-

-will iterate over all characters of the file, -starting at the current position. -Unlike io.lines, this function does not close the file -when the loop ends. - - -

-In case of errors this function raises the error, -instead of returning an error code. - - - - -

-

file:read (···)

- - -

-Reads the file file, -according to the given formats, which specify what to read. -For each format, -the function returns a string or a number with the characters read, -or nil if it cannot read data with the specified format. -(In this latter case, -the function does not read subsequent formats.) -When called without formats, -it uses a default format that reads the next line -(see below). - - -

-The available formats are - -

    - -
  • "n": -reads a numeral and returns it as a float or an integer, -following the lexical conventions of Lua. -(The numeral may have leading spaces and a sign.) -This format always reads the longest input sequence that -is a valid prefix for a numeral; -if that prefix does not form a valid numeral -(e.g., an empty string, "0x", or "3.4e-"), -it is discarded and the function returns nil. -
    • - -
  • "a": -reads the whole file, starting at the current position. -On end of file, it returns the empty string. -
    • - -
  • "l": -reads the next line skipping the end of line, -returning nil on end of file. -This is the default format. -
    • - -
  • "L": -reads the next line keeping the end-of-line character (if present), -returning nil on end of file. -
    • - -
  • number: -reads a string with up to this number of bytes, -returning nil on end of file. -If number is zero, -it reads nothing and returns an empty string, -or nil on end of file. -
    • - -

-The formats "l" and "L" should be used only for text files. - - - - -

-

file:seek ([whence [, offset]])

- - -

-Sets and gets the file position, -measured from the beginning of the file, -to the position given by offset plus a base -specified by the string whence, as follows: - -

    -
  • "set": base is position 0 (beginning of the file);
    • -
  • "cur": base is current position;
    • -
  • "end": base is end of file;
    • -

-In case of success, seek returns the final file position, -measured in bytes from the beginning of the file. -If seek fails, it returns nil, -plus a string describing the error. - - -

-The default value for whence is "cur", -and for offset is 0. -Therefore, the call file:seek() returns the current -file position, without changing it; -the call file:seek("set") sets the position to the -beginning of the file (and returns 0); -and the call file:seek("end") sets the position to the -end of the file, and returns its size. - - - - -

-

file:setvbuf (mode [, size])

- - -

-Sets the buffering mode for an output file. -There are three available modes: - -

    - -
  • "no": -no buffering; the result of any output operation appears immediately. -
    • - -
  • "full": -full buffering; output operation is performed only -when the buffer is full or when -you explicitly flush the file (see io.flush). -
    • - -
  • "line": -line buffering; output is buffered until a newline is output -or there is any input from some special files -(such as a terminal device). -
    • - -

-For the last two cases, size -specifies the size of the buffer, in bytes. -The default is an appropriate size. - - - - -

-

file:write (···)

- - -

-Writes the value of each of its arguments to file. -The arguments must be strings or numbers. - - -

-In case of success, this function returns file. -Otherwise it returns nil plus a string describing the error. - - - - - - - -

6.9 – Operating System Facilities

- -

-This library is implemented through table os. - - -

-

os.clock ()

- - -

-Returns an approximation of the amount in seconds of CPU time -used by the program. - - - - -

-

os.date ([format [, time]])

- - -

-Returns a string or a table containing date and time, -formatted according to the given string format. - - -

-If the time argument is present, -this is the time to be formatted -(see the os.time function for a description of this value). -Otherwise, date formats the current time. - - -

-If format starts with '!', -then the date is formatted in Coordinated Universal Time. -After this optional character, -if format is the string "*t", -then date returns a table with the following fields: -year, month (1–12), day (1–31), -hour (0–23), min (0–59), sec (0–61), -wday (weekday, 1–7, Sunday is 1), -yday (day of the year, 1–366), -and isdst (daylight saving flag, a boolean). -This last field may be absent -if the information is not available. - - -

-If format is not "*t", -then date returns the date as a string, -formatted according to the same rules as the ISO C function strftime. - - -

-When called without arguments, -date returns a reasonable date and time representation that depends on -the host system and on the current locale. -(More specifically, os.date() is equivalent to os.date("%c").) - - -

-In non-POSIX systems, -this function may be not thread safe -because of its reliance on C function gmtime and C function localtime. - - - - -

-

os.difftime (t2, t1)

- - -

-Returns the difference, in seconds, -from time t1 to time t2 -(where the times are values returned by os.time). -In POSIX, Windows, and some other systems, -this value is exactly t2-t1. - - - - -

-

os.execute ([command])

- - -

-This function is equivalent to the ISO C function system. -It passes command to be executed by an operating system shell. -Its first result is true -if the command terminated successfully, -or nil otherwise. -After this first result -the function returns a string plus a number, -as follows: - -

    - -
  • "exit": -the command terminated normally; -the following number is the exit status of the command. -
    • - -
  • "signal": -the command was terminated by a signal; -the following number is the signal that terminated the command. -
    • - -
- -

-When called without a command, -os.execute returns a boolean that is true if a shell is available. - - - - -

-

os.exit ([code [, close]])

- - -

-Calls the ISO C function exit to terminate the host program. -If code is true, -the returned status is EXIT_SUCCESS; -if code is false, -the returned status is EXIT_FAILURE; -if code is a number, -the returned status is this number. -The default value for code is true. - - -

-If the optional second argument close is true, -closes the Lua state before exiting. - - - - -

-

os.getenv (varname)

- - -

-Returns the value of the process environment variable varname, -or nil if the variable is not defined. - - - - -

-

os.remove (filename)

- - -

-Deletes the file (or empty directory, on POSIX systems) -with the given name. -If this function fails, it returns nil, -plus a string describing the error and the error code. -Otherwise, it returns true. - - - - -

-

os.rename (oldname, newname)

- - -

-Renames the file or directory named oldname to newname. -If this function fails, it returns nil, -plus a string describing the error and the error code. -Otherwise, it returns true. - - - - -

-

os.setlocale (locale [, category])

- - -

-Sets the current locale of the program. -locale is a system-dependent string specifying a locale; -category is an optional string describing which category to change: -"all", "collate", "ctype", -"monetary", "numeric", or "time"; -the default category is "all". -The function returns the name of the new locale, -or nil if the request cannot be honored. - - -

-If locale is the empty string, -the current locale is set to an implementation-defined native locale. -If locale is the string "C", -the current locale is set to the standard C locale. - - -

-When called with nil as the first argument, -this function only returns the name of the current locale -for the given category. - - -

-This function may be not thread safe -because of its reliance on C function setlocale. - - - - -

-

os.time ([table])

- - -

-Returns the current time when called without arguments, -or a time representing the local date and time specified by the given table. -This table must have fields year, month, and day, -and may have fields -hour (default is 12), -min (default is 0), -sec (default is 0), -and isdst (default is nil). -Other fields are ignored. -For a description of these fields, see the os.date function. - - -

-The values in these fields do not need to be inside their valid ranges. -For instance, if sec is -10, -it means -10 seconds from the time specified by the other fields; -if hour is 1000, -it means +1000 hours from the time specified by the other fields. - - -

-The returned value is a number, whose meaning depends on your system. -In POSIX, Windows, and some other systems, -this number counts the number -of seconds since some given start time (the "epoch"). -In other systems, the meaning is not specified, -and the number returned by time can be used only as an argument to -os.date and os.difftime. - - - - -

-

os.tmpname ()

- - -

-Returns a string with a file name that can -be used for a temporary file. -The file must be explicitly opened before its use -and explicitly removed when no longer needed. - - -

-In POSIX systems, -this function also creates a file with that name, -to avoid security risks. -(Someone else might create the file with wrong permissions -in the time between getting the name and creating the file.) -You still have to open the file to use it -and to remove it (even if you do not use it). - - -

-When possible, -you may prefer to use io.tmpfile, -which automatically removes the file when the program ends. - - - - - - - -

6.10 – The Debug Library

- -

-This library provides -the functionality of the debug interface (§4.9) to Lua programs. -You should exert care when using this library. -Several of its functions -violate basic assumptions about Lua code -(e.g., that variables local to a function -cannot be accessed from outside; -that userdata metatables cannot be changed by Lua code; -that Lua programs do not crash) -and therefore can compromise otherwise secure code. -Moreover, some functions in this library may be slow. - - -

-All functions in this library are provided -inside the debug table. -All functions that operate over a thread -have an optional first argument which is the -thread to operate over. -The default is always the current thread. - - -

-

debug.debug ()

- - -

-Enters an interactive mode with the user, -running each string that the user enters. -Using simple commands and other debug facilities, -the user can inspect global and local variables, -change their values, evaluate expressions, and so on. -A line containing only the word cont finishes this function, -so that the caller continues its execution. - - -

-Note that commands for debug.debug are not lexically nested -within any function and so have no direct access to local variables. - - - - -

-

debug.gethook ([thread])

- - -

-Returns the current hook settings of the thread, as three values: -the current hook function, the current hook mask, -and the current hook count -(as set by the debug.sethook function). - - - - -

-

debug.getinfo ([thread,] f [, what])

- - -

-Returns a table with information about a function. -You can give the function directly -or you can give a number as the value of f, -which means the function running at level f of the call stack -of the given thread: -level 0 is the current function (getinfo itself); -level 1 is the function that called getinfo -(except for tail calls, which do not count on the stack); -and so on. -If f is a number larger than the number of active functions, -then getinfo returns nil. - - -

-The returned table can contain all the fields returned by lua_getinfo, -with the string what describing which fields to fill in. -The default for what is to get all information available, -except the table of valid lines. -If present, -the option 'f' -adds a field named func with the function itself. -If present, -the option 'L' -adds a field named activelines with the table of -valid lines. - - -

-For instance, the expression debug.getinfo(1,"n").name returns -a name for the current function, -if a reasonable name can be found, -and the expression debug.getinfo(print) -returns a table with all available information -about the print function. - - - - -

-

debug.getlocal ([thread,] f, local)

- - -

-This function returns the name and the value of the local variable -with index local of the function at level f of the stack. -This function accesses not only explicit local variables, -but also parameters, temporaries, etc. - - -

-The first parameter or local variable has index 1, and so on, -following the order that they are declared in the code, -counting only the variables that are active -in the current scope of the function. -Negative indices refer to vararg arguments; --1 is the first vararg argument. -The function returns nil if there is no variable with the given index, -and raises an error when called with a level out of range. -(You can call debug.getinfo to check whether the level is valid.) - - -

-Variable names starting with '(' (open parenthesis) -represent variables with no known names -(internal variables such as loop control variables, -and variables from chunks saved without debug information). - - -

-The parameter f may also be a function. -In that case, getlocal returns only the name of function parameters. - - - - -

-

debug.getmetatable (value)

- - -

-Returns the metatable of the given value -or nil if it does not have a metatable. - - - - -

-

debug.getregistry ()

- - -

-Returns the registry table (see §4.5). - - - - -

-

debug.getupvalue (f, up)

- - -

-This function returns the name and the value of the upvalue -with index up of the function f. -The function returns nil if there is no upvalue with the given index. - - -

-Variable names starting with '(' (open parenthesis) -represent variables with no known names -(variables from chunks saved without debug information). - - - - -

-

debug.getuservalue (u)

- - -

-Returns the Lua value associated to u. -If u is not a full userdata, -returns nil. - - - - -

-

debug.sethook ([thread,] hook, mask [, count])

- - -

-Sets the given function as a hook. -The string mask and the number count describe -when the hook will be called. -The string mask may have any combination of the following characters, -with the given meaning: - -

    -
  • 'c': the hook is called every time Lua calls a function;
    • -
  • 'r': the hook is called every time Lua returns from a function;
    • -
  • 'l': the hook is called every time Lua enters a new line of code.
    • -

-Moreover, -with a count different from zero, -the hook is called also after every count instructions. - - -

-When called without arguments, -debug.sethook turns off the hook. - - -

-When the hook is called, its first argument is a string -describing the event that has triggered its call: -"call" (or "tail call"), -"return", -"line", and "count". -For line events, -the hook also gets the new line number as its second parameter. -Inside a hook, -you can call getinfo with level 2 to get more information about -the running function -(level 0 is the getinfo function, -and level 1 is the hook function). - - - - -

-

debug.setlocal ([thread,] level, local, value)

- - -

-This function assigns the value value to the local variable -with index local of the function at level level of the stack. -The function returns nil if there is no local -variable with the given index, -and raises an error when called with a level out of range. -(You can call getinfo to check whether the level is valid.) -Otherwise, it returns the name of the local variable. - - -

-See debug.getlocal for more information about -variable indices and names. - - - - -

-

debug.setmetatable (value, table)

- - -

-Sets the metatable for the given value to the given table -(which can be nil). -Returns value. - - - - -

-

debug.setupvalue (f, up, value)

- - -

-This function assigns the value value to the upvalue -with index up of the function f. -The function returns nil if there is no upvalue -with the given index. -Otherwise, it returns the name of the upvalue. - - - - -

-

debug.setuservalue (udata, value)

- - -

-Sets the given value as -the Lua value associated to the given udata. -udata must be a full userdata. - - -

-Returns udata. - - - - -

-

debug.traceback ([thread,] [message [, level]])

- - -

-If message is present but is neither a string nor nil, -this function returns message without further processing. -Otherwise, -it returns a string with a traceback of the call stack. -The optional message string is appended -at the beginning of the traceback. -An optional level number tells at which level -to start the traceback -(default is 1, the function calling traceback). - - - - -

-

debug.upvalueid (f, n)

- - -

-Returns a unique identifier (as a light userdata) -for the upvalue numbered n -from the given function. - - -

-These unique identifiers allow a program to check whether different -closures share upvalues. -Lua closures that share an upvalue -(that is, that access a same external local variable) -will return identical ids for those upvalue indices. - - - - -

-

debug.upvaluejoin (f1, n1, f2, n2)

- - -

-Make the n1-th upvalue of the Lua closure f1 -refer to the n2-th upvalue of the Lua closure f2. - - - - - - - -

7 – Lua Standalone

- -

-Although Lua has been designed as an extension language, -to be embedded in a host C program, -it is also frequently used as a standalone language. -An interpreter for Lua as a standalone language, -called simply lua, -is provided with the standard distribution. -The standalone interpreter includes -all standard libraries, including the debug library. -Its usage is: - -

-     lua [options] [script [args]]
-

-The options are: - -

    -
  • -e stat: executes string stat;
    • -
  • -l mod: "requires" mod and assigns the - result to global @mod;
    • -
  • -i: enters interactive mode after running script;
    • -
  • -v: prints version information;
    • -
  • -E: ignores environment variables;
    • -
  • --: stops handling options;
    • -
  • -: executes stdin as a file and stops handling options.
    • -

-After handling its options, lua runs the given script. -When called without arguments, -lua behaves as lua -v -i -when the standard input (stdin) is a terminal, -and as lua - otherwise. - - -

-When called without option -E, -the interpreter checks for an environment variable LUA_INIT_5_3 -(or LUA_INIT if the versioned name is not defined) -before running any argument. -If the variable content has the format @filename, -then lua executes the file. -Otherwise, lua executes the string itself. - - -

-When called with option -E, -besides ignoring LUA_INIT, -Lua also ignores -the values of LUA_PATH and LUA_CPATH, -setting the values of -package.path and package.cpath -with the default paths defined in luaconf.h. - - -

-All options are handled in order, except -i and -E. -For instance, an invocation like - -

-     $ lua -e'a=1' -e 'print(a)' script.lua
-

-will first set a to 1, then print the value of a, -and finally run the file script.lua with no arguments. -(Here $ is the shell prompt. Your prompt may be different.) - - -

-Before running any code, -lua collects all command-line arguments -in a global table called arg. -The script name goes to index 0, -the first argument after the script name goes to index 1, -and so on. -Any arguments before the script name -(that is, the interpreter name plus its options) -go to negative indices. -For instance, in the call - -

-     $ lua -la b.lua t1 t2
-

-the table is like this: - -

-     arg = { [-2] = "lua", [-1] = "-la",
-             [0] = "b.lua",
-             [1] = "t1", [2] = "t2" }
-

-If there is no script in the call, -the interpreter name goes to index 0, -followed by the other arguments. -For instance, the call - -

-     $ lua -e "print(arg[1])"
-

-will print "-e". -If there is a script, -the script is called with arguments -arg[1], ···, arg[#arg]. -(Like all chunks in Lua, -the script is compiled as a vararg function.) - - -

-In interactive mode, -Lua repeatedly prompts and waits for a line. -After reading a line, -Lua first try to interpret the line as an expression. -If it succeeds, it prints its value. -Otherwise, it interprets the line as a statement. -If you write an incomplete statement, -the interpreter waits for its completion -by issuing a different prompt. - - -

-If the global variable _PROMPT contains a string, -then its value is used as the prompt. -Similarly, if the global variable _PROMPT2 contains a string, -its value is used as the secondary prompt -(issued during incomplete statements). - - -

-In case of unprotected errors in the script, -the interpreter reports the error to the standard error stream. -If the error object is not a string but -has a metamethod __tostring, -the interpreter calls this metamethod to produce the final message. -Otherwise, the interpreter converts the error object to a string -and adds a stack traceback to it. - - -

-When finishing normally, -the interpreter closes its main Lua state -(see lua_close). -The script can avoid this step by -calling os.exit to terminate. - - -

-To allow the use of Lua as a -script interpreter in Unix systems, -the standalone interpreter skips -the first line of a chunk if it starts with #. -Therefore, Lua scripts can be made into executable programs -by using chmod +x and the #! form, -as in - -

-     #!/usr/local/bin/lua
-

-(Of course, -the location of the Lua interpreter may be different in your machine. -If lua is in your PATH, -then - -

-     #!/usr/bin/env lua
-

-is a more portable solution.) - - - -

8 – Incompatibilities with the Previous Version

- -

-Here we list the incompatibilities that you may find when moving a program -from Lua 5.2 to Lua 5.3. -You can avoid some incompatibilities by compiling Lua with -appropriate options (see file luaconf.h). -However, -all these compatibility options will be removed in the future. - - -

-Lua versions can always change the C API in ways that -do not imply source-code changes in a program, -such as the numeric values for constants -or the implementation of functions as macros. -Therefore, -you should not assume that binaries are compatible between -different Lua versions. -Always recompile clients of the Lua API when -using a new version. - - -

-Similarly, Lua versions can always change the internal representation -of precompiled chunks; -precompiled chunks are not compatible between different Lua versions. - - -

-The standard paths in the official distribution may -change between versions. - - - -

8.1 – Changes in the Language

-
    - -
  • -The main difference between Lua 5.2 and Lua 5.3 is the -introduction of an integer subtype for numbers. -Although this change should not affect "normal" computations, -some computations -(mainly those that involve some kind of overflow) -can give different results. - - -

    -You can fix these differences by forcing a number to be a float -(in Lua 5.2 all numbers were float), -in particular writing constants with an ending .0 -or using x = x + 0.0 to convert a variable. -(This recommendation is only for a quick fix -for an occasional incompatibility; -it is not a general guideline for good programming. -For good programming, -use floats where you need floats -and integers where you need integers.) -

    • - -
  • -The conversion of a float to a string now adds a .0 suffix -to the result if it looks like an integer. -(For instance, the float 2.0 will be printed as 2.0, -not as 2.) -You should always use an explicit format -when you need a specific format for numbers. - - -

    -(Formally this is not an incompatibility, -because Lua does not specify how numbers are formatted as strings, -but some programs assumed a specific format.) -

    • - -
  • -The generational mode for the garbage collector was removed. -(It was an experimental feature in Lua 5.2.) -
    • - -
- - - - -

8.2 – Changes in the Libraries

-
    - -
  • -The bit32 library has been deprecated. -It is easy to require a compatible external library or, -better yet, to replace its functions with appropriate bitwise operations. -(Keep in mind that bit32 operates on 32-bit integers, -while the bitwise operators in Lua 5.3 operate on Lua integers, -which by default have 64 bits.) -
    • - -
  • -The Table library now respects metamethods -for setting and getting elements. -
    • - -
  • -The ipairs iterator now respects metamethods and -its __ipairs metamethod has been deprecated. -
    • - -
  • -Option names in io.read do not have a starting '*' anymore. -For compatibility, Lua will continue to accept (and ignore) this character. -
    • - -
  • -The following functions were deprecated in the mathematical library: -atan2, cosh, sinh, tanh, pow, -frexp, and ldexp. -You can replace math.pow(x,y) with x^y; -you can replace math.atan2 with math.atan, -which now accepts one or two arguments; -you can replace math.ldexp(x,exp) with x * 2.0^exp. -For the other operations, -you can either use an external library or -implement them in Lua. -
    • - -
  • -The searcher for C loaders used by require -changed the way it handles versioned names. -Now, the version should come after the module name -(as is usual in most other tools). -For compatibility, that searcher still tries the old format -if it cannot find an open function according to the new style. -(Lua 5.2 already worked that way, -but it did not document the change.) -
    • - -
  • -The call collectgarbage("count") now returns only one result. -(You can compute that second result from the fractional part -of the first result.) -
    • - -
- - - - -

8.3 – Changes in the API

- - -
    - -
  • -Continuation functions now receive as arguments what they needed -to get through lua_getctx, -so lua_getctx has been removed. -Adapt your code accordingly. -
    • - -
  • -Function lua_dump has an extra parameter, strip. -Use 0 as the value of this parameter to get the old behavior. -
    • - -
  • -Functions to inject/project unsigned integers -(lua_pushunsigned, lua_tounsigned, lua_tounsignedx, -luaL_checkunsigned, luaL_optunsigned) -were deprecated. -Use their signed equivalents with a type cast. -
    • - -
  • -Macros to project non-default integer types -(luaL_checkint, luaL_optint, luaL_checklong, luaL_optlong) -were deprecated. -Use their equivalent over lua_Integer with a type cast -(or, when possible, use lua_Integer in your code). -
    • - -
- - - - -

9 – The Complete Syntax of Lua

- -

-Here is the complete syntax of Lua in extended BNF. -As usual in extended BNF, -{A} means 0 or more As, -and [A] means an optional A. -(For operator precedences, see §3.4.8; -for a description of the terminals -Name, Numeral, -and LiteralString, see §3.1.) - - - - -

-
-	chunk ::= block
-
-	block ::= {stat} [retstat]
-
-	stat ::=  ‘;’ | 
-		 varlist ‘=’ explist | 
-		 functioncall | 
-		 label | 
-		 break | 
-		 goto Name | 
-		 do block end | 
-		 while exp do block end | 
-		 repeat block until exp | 
-		 if exp then block {elseif exp then block} [else block] end | 
-		 for Name ‘=’ exp ‘,’ exp [‘,’ exp] do block end | 
-		 for namelist in explist do block end | 
-		 function funcname funcbody | 
-		 local function Name funcbody | 
-		 local namelist [‘=’ explist] 
-
-	retstat ::= return [explist] [‘;’]
-
-	label ::= ‘::’ Name ‘::’
-
-	funcname ::= Name {‘.’ Name} [‘:’ Name]
-
-	varlist ::= var {‘,’ var}
-
-	var ::=  Name | prefixexp ‘[’ exp ‘]’ | prefixexp ‘.’ Name 
-
-	namelist ::= Name {‘,’ Name}
-
-	explist ::= exp {‘,’ exp}
-
-	exp ::=  nil | false | true | Numeral | LiteralString | ‘...’ | functiondef | 
-		 prefixexp | tableconstructor | exp binop exp | unop exp 
-
-	prefixexp ::= var | functioncall | ‘(’ exp ‘)’
-
-	functioncall ::=  prefixexp args | prefixexp ‘:’ Name args 
-
-	args ::=  ‘(’ [explist] ‘)’ | tableconstructor | LiteralString 
-
-	functiondef ::= function funcbody
-
-	funcbody ::= ‘(’ [parlist] ‘)’ block end
-
-	parlist ::= namelist [‘,’ ‘...’] | ‘...’
-
-	tableconstructor ::= ‘{’ [fieldlist] ‘}’
-
-	fieldlist ::= field {fieldsep field} [fieldsep]
-
-	field ::= ‘[’ exp ‘]’ ‘=’ exp | Name ‘=’ exp | exp
-
-	fieldsep ::= ‘,’ | ‘;’
-
-	binop ::=  ‘+’ | ‘-’ | ‘*’ | ‘/’ | ‘//’ | ‘^’ | ‘%’ | 
-		 ‘&’ | ‘~’ | ‘|’ | ‘>>’ | ‘<<’ | ‘..’ | 
-		 ‘<’ | ‘<=’ | ‘>’ | ‘>=’ | ‘==’ | ‘~=’ | 
-		 and | or
-
-	unop ::= ‘-’ | not | ‘#’ | ‘~’
-
-
- -

- - - - - - - - -

-Last update: -Tue Jun 26 13:16:37 -03 2018 -

- - - - -- cgit v1.2.3