X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5b02c8a11f0e0d284eff32cfde1fcd2a4b2e659d..b9d880d6382e24156cdce4ae0390c843cc6208d9:/src/png/libpng.3 diff --git a/src/png/libpng.3 b/src/png/libpng.3 index e7fa62e6ad..0d4d82958f 100644 --- a/src/png/libpng.3 +++ b/src/png/libpng.3 @@ -1,6 +1,6 @@ -.TH LIBPNG 3 "August 15, 2004" +.TH LIBPNG 3 "September 12, 2004" .SH NAME -libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6 +libpng \- Portable Network Graphics (PNG) Reference Library 1.2.7 .SH SYNOPSIS \fI\fB @@ -402,6 +402,14 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.2.6 \fI\fB +\fB#if \fI!defined(PNG_1_0_X) + +\fBvoid png_set_add_alpha (png_structp \fP\fIpng_ptr\fP\fB, png_uint_32 \fP\fIfiller\fP\fB, int \fIflags\fP\fB);\fP + +\fI\fB#endif + +\fI\fB + \fBvoid png_set_background (png_structp \fP\fIpng_ptr\fP\fB, png_color_16p \fP\fIbackground_color\fP\fB, int \fP\fIbackground_gamma_code\fP\fB, int \fP\fIneed_expand\fP\fB, double \fIbackground_gamma\fP\fB);\fP \fI\fB @@ -773,7 +781,7 @@ Following is a copy of the libpng.txt file that accompanies libpng. .SH LIBPNG.TXT libpng.txt - A description on how to use and modify libpng - libpng version 1.2.6 - August 15, 2004 + libpng version 1.2.7 - September 12, 2004 Updated and distributed by Glenn Randers-Pehrson Copyright (c) 1998-2004 Glenn Randers-Pehrson @@ -810,19 +818,23 @@ 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-1.2 specification is available at -and at . +The PNG specification (second edition), November 2003, is available as +a W3C Recommendation and as an ISO Standard (ISO/IEC 15948:2003 (E)) at + The PNG-1.0 specification is available -as RFC 2083 and as a +as RFC 2083 and as a W3C Recommendation . Some additional chunks are described in the special-purpose public chunks -documents at . +documents at . Other information about PNG, and the latest version of libpng, can be found at the PNG home -page, -and at . +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 @@ -855,7 +867,6 @@ same instance of a structure. Note: thread safety may be defeated by use of some of the MMX assembler code in pnggccrd.c, which is only compiled when the user defines PNG_THREAD_UNSAFE_OK. - .SH II. Structures There are two main structures that are important to libpng, png_struct @@ -1073,28 +1084,28 @@ To inform libpng about your function, use png_set_read_status_fn(png_ptr, read_row_callback); -%-%.SS Width and height limits -%-% -%-%The PNG specification allows the width and height of an image to be as -%-%large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns. -%-%Since very few applications really need to process such large images, -%-%we have imposed an arbitrary 1-million limit on rows and columns. -%-%Larger images will be rejected immediately with a png_error() call. If -%-%you wish to override this limit, you can use -%-% -%-% png_set_user_limits(png_ptr, width_max, height_max); -%-% -%-%to set your own limits, or use width_max = height_max = 0x7fffffffL -%-%to allow all valid dimensions (libpng may reject some very large images -%-%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(). -%-%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); -%-% +.SS Width and height limits + +The PNG specification allows the width and height of an image to be as +large as 2^31-1 (0x7fffffff), or about 2.147 billion rows and columns. +Since very few applications really need to process such large images, +we have imposed an arbitrary 1-million limit on rows and columns. +Larger images will be rejected immediately with a png_error() call. If +you wish to override this limit, you can use + + png_set_user_limits(png_ptr, width_max, height_max); + +to set your own limits, or use width_max = height_max = 0x7fffffffL +to allow all valid dimensions (libpng may reject some very large images +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(). +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); + .SS Unknown-chunk handling Now you get to set the way the library processes unknown chunks in the @@ -1170,6 +1181,9 @@ 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 @@ -1534,14 +1548,14 @@ unless the library has been told to transform it into another format. For example, 4 bit/pixel paletted or grayscale data will be returned 2 pixels/byte with the leftmost pixel in the high-order bits of the byte, unless png_set_packing() is called. 8-bit RGB data will be stored -in RGB RGB RGB format unless png_set_filler() is called to insert filler -bytes, either before or after each RGB triplet. 16-bit RGB data will -be returned RRGGBB RRGGBB, with the most significant byte of the color -value first, unless png_set_strip_16() is called to transform it to -regular RGB RGB triplets, or png_set_filler() is called to insert -filler bytes, either before or after each RRGGBB triplet. Similarly, -8-bit or 16-bit grayscale data can be modified with png_set_filler() -or png_set_strip_16(). +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_strip_16() is called to +transform it to regular RGB RGB triplets, or png_set_filler|add alpha() +is called to insert filler bytes, either before or after each RRGGBB +triplet. Similarly, 8-bit or 16-bit grayscale data can be modified with +png_set_filler(), png_set_add_alpha(), or png_set_strip_16(). The following code transforms grayscale images of less than 8 to 8 bits, changes paletted images to RGB, and adds a full alpha channel if there is @@ -1626,6 +1640,16 @@ does not affect images that already have full alpha channels. To add an opaque alpha channel, use filler=0xff or 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. +This function became available 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: @@ -2770,6 +2794,9 @@ 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(). + .SS The low-level write interface If you are going the low-level route instead, you are now ready to @@ -3462,126 +3489,126 @@ When PNG_DEBUG = 1, the macros are defined, but only png_debug statements having level = 0 will be printed. There aren't any such statements in this version of libpng, but if you insert some they will be printed. -%-%.SH VI. Runtime optimization -%-% -%-%A new feature in libpng 1.2.0 is the ability to dynamically switch between -%-%standard and optimized versions of some routines. Currently these are -%-%limited to three computationally intensive tasks when reading PNG files: -%-%decoding row filters, expanding interlacing, and combining interlaced or -%-%transparent row data with previous row data. Currently the optimized -%-%versions are available only for x86 (Intel, AMD, etc.) platforms with -%-%MMX support, though this may change in future versions. (For example, -%-%the non-MMX assembler optimizations for zlib might become similarly -%-%runtime-selectable in future releases, in which case libpng could be -%-%extended to support them. Alternatively, the compile-time choice of -%-%floating-point versus integer routines for gamma correction might become -%-%runtime-selectable.) -%-% -%-%Because such optimizations tend to be very platform- and compiler-dependent, -%-%both in how they are written and in how they perform, the new runtime code -%-%in libpng has been written to allow programs to query, enable, and disable -%-%either specific optimizations or all such optimizations. For example, to -%-%enable all possible optimizations (bearing in mind that some "optimizations" -%-%may actually run more slowly in rare cases): -%-% -%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) -%-% png_uint_32 mask, flags; -%-% -%-% flags = png_get_asm_flags(png_ptr); -%-% mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE); -%-% png_set_asm_flags(png_ptr, flags | mask); -%-% #endif -%-% -%-%To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ -%-%by itself when calling png_get_asm_flagmask(); similarly for optimizing -%-%only writing. To disable all optimizations: -%-% -%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) -%-% flags = png_get_asm_flags(png_ptr); -%-% mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE); -%-% png_set_asm_flags(png_ptr, flags & ~mask); -%-% #endif -%-% -%-%To enable or disable only MMX-related features, use png_get_mmx_flagmask() -%-%in place of png_get_asm_flagmask(). The mmx version takes one additional -%-%parameter: -%-% -%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) -%-% int selection = PNG_SELECT_READ | PNG_SELECT_WRITE; -%-% int compilerID; -%-% -%-% mask = png_get_mmx_flagmask(selection, &compilerID); -%-% #endif -%-% -%-%On return, compilerID will indicate which version of the MMX assembler -%-%optimizations was compiled. Currently two flavors exist: Microsoft -%-%Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2). -%-%On non-x86 platforms or on systems compiled without MMX optimizations, a -%-%value of -1 is used. -%-% -%-%Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return -%-%all valid, settable optimization bits for the version of the library that's -%-%currently in use. In the case of shared (dynamically linked) libraries, -%-%this may include optimizations that did not exist at the time the code was -%-%written and compiled. It is also possible, of course, to enable only known, -%-%specific optimizations; for example: -%-% -%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) -%-% flags = 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_set_asm_flags(png_ptr, flags); -%-% #endif -%-% -%-%This method would enable only the MMX read-optimizations available at the -%-%time of libpng 1.2.0's release, regardless of whether a later version of -%-%the DLL were actually being used. (Also note that these functions did not -%-%exist in versions older than 1.2.0, so any attempt to run a dynamically -%-%linked app on such an older version would fail.) -%-% -%-%To determine whether the processor supports MMX instructions at all, use -%-%the png_mmx_support() function: -%-% -%-% #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) -%-% mmxsupport = png_mmx_support(); -%-% #endif -%-% -%-%It returns -1 if MMX support is not compiled into libpng, 0 if MMX code -%-%is compiled but MMX is not supported by the processor, or 1 if MMX support -%-%is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(), -%-%and png_get_asm_flagmask() all may be called without allocating and ini- -%-%tializing any PNG structures (for example, as part of a usage screen or -%-%"about" box). -%-% -%-%The following code can be used to prevent an application from using the -%-%thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK -%-%defined: -%-% -%-%#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \ -%-% && defined(PNG_THREAD_UNSAFE_OK) -%-% /* Disable thread-unsafe features of pnggccrd */ -%-% if (png_access_version() >= 10200) -%-% { -%-% png_uint_32 mmx_disable_mask = 0; -%-% png_uint_32 asm_flags; -%-% -%-% mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \ -%-% | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \ -%-% | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \ -%-% | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ); -%-% asm_flags = png_get_asm_flags(png_ptr); -%-% png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask); -%-% } -%-%#endif -%-% -%-%For more extensive examples of runtime querying, enabling and disabling -%-%of optimized features, see contrib/gregbook/readpng2.c in the libpng -%-%source-code distribution. -%-% -.SH VI. MNG support +.SH VI. Runtime optimization + +A new feature in libpng 1.2.0 is the ability to dynamically switch between +standard and optimized versions of some routines. Currently these are +limited to three computationally intensive tasks when reading PNG files: +decoding row filters, expanding interlacing, and combining interlaced or +transparent row data with previous row data. Currently the optimized +versions are available only for x86 (Intel, AMD, etc.) platforms with +MMX support, though this may change in future versions. (For example, +the non-MMX assembler optimizations for zlib might become similarly +runtime-selectable in future releases, in which case libpng could be +extended to support them. Alternatively, the compile-time choice of +floating-point versus integer routines for gamma correction might become +runtime-selectable.) + +Because such optimizations tend to be very platform- and compiler-dependent, +both in how they are written and in how they perform, the new runtime code +in libpng has been written to allow programs to query, enable, and disable +either specific optimizations or all such optimizations. For example, to +enable all possible optimizations (bearing in mind that some "optimizations" +may actually run more slowly in rare cases): + + #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) + png_uint_32 mask, flags; + + flags = png_get_asm_flags(png_ptr); + mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE); + png_set_asm_flags(png_ptr, flags | mask); + #endif + +To enable only optimizations relevant to reading PNGs, use PNG_SELECT_READ +by itself when calling png_get_asm_flagmask(); similarly for optimizing +only writing. To disable all optimizations: + + #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) + flags = png_get_asm_flags(png_ptr); + mask = png_get_asm_flagmask(PNG_SELECT_READ | PNG_SELECT_WRITE); + png_set_asm_flags(png_ptr, flags & ~mask); + #endif + +To enable or disable only MMX-related features, use png_get_mmx_flagmask() +in place of png_get_asm_flagmask(). The mmx version takes one additional +parameter: + + #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) + int selection = PNG_SELECT_READ | PNG_SELECT_WRITE; + int compilerID; + + mask = png_get_mmx_flagmask(selection, &compilerID); + #endif + +On return, compilerID will indicate which version of the MMX assembler +optimizations was compiled. Currently two flavors exist: Microsoft +Visual C++ (compilerID == 1) and GNU C (a.k.a. gcc/gas, compilerID == 2). +On non-x86 platforms or on systems compiled without MMX optimizations, a +value of -1 is used. + +Note that both png_get_asm_flagmask() and png_get_mmx_flagmask() return +all valid, settable optimization bits for the version of the library that's +currently in use. In the case of shared (dynamically linked) libraries, +this may include optimizations that did not exist at the time the code was +written and compiled. It is also possible, of course, to enable only known, +specific optimizations; for example: + + #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) + flags = 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_set_asm_flags(png_ptr, flags); + #endif + +This method would enable only the MMX read-optimizations available at the +time of libpng 1.2.0's release, regardless of whether a later version of +the DLL were actually being used. (Also note that these functions did not +exist in versions older than 1.2.0, so any attempt to run a dynamically +linked app on such an older version would fail.) + +To determine whether the processor supports MMX instructions at all, use +the png_mmx_support() function: + + #if defined(PNG_LIBPNG_VER) && (PNG_LIBPNG_VER >= 10200) + mmxsupport = png_mmx_support(); + #endif + +It returns -1 if MMX support is not compiled into libpng, 0 if MMX code +is compiled but MMX is not supported by the processor, or 1 if MMX support +is fully available. Note that png_mmx_support(), png_get_mmx_flagmask(), +and png_get_asm_flagmask() all may be called without allocating and ini- +tializing any PNG structures (for example, as part of a usage screen or +"about" box). + +The following code can be used to prevent an application from using the +thread_unsafe features, even if libpng was built with PNG_THREAD_UNSAFE_OK +defined: + +#if defined(PNG_USE_PNGGCCRD) && defined(PNG_ASSEMBLER_CODE_SUPPORTED) \ + && defined(PNG_THREAD_UNSAFE_OK) + /* Disable thread-unsafe features of pnggccrd */ + if (png_access_version() >= 10200) + { + png_uint_32 mmx_disable_mask = 0; + png_uint_32 asm_flags; + + mmx_disable_mask |= ( PNG_ASM_FLAG_MMX_READ_COMBINE_ROW \ + | PNG_ASM_FLAG_MMX_READ_FILTER_SUB \ + | PNG_ASM_FLAG_MMX_READ_FILTER_AVG \ + | PNG_ASM_FLAG_MMX_READ_FILTER_PAETH ); + asm_flags = png_get_asm_flags(png_ptr); + png_set_asm_flags(png_ptr, asm_flags & ~mmx_disable_mask); + } +#endif + +For more extensive examples of runtime querying, enabling and disabling +of optimized features, see contrib/gregbook/readpng2.c in the libpng +source-code distribution. + +.SH 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. @@ -3606,7 +3633,7 @@ or any other MNG chunks; your application must provide its own support for them. You may wish to consider using libmng (available at http://www.libmng.com) instead. -.SH VII. Changes to Libpng from version 0.88 +.SH 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 @@ -3655,15 +3682,15 @@ application: png_uint_32 application_vn = PNG_LIBPNG_VER; -.SH VII. Y2K Compliance in libpng +.SH IX. Y2K Compliance in libpng -August 15, 2004 +September 12, 2004 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.2.6 are Y2K compliant. It is my belief that earlier +upward through 1.2.7 are Y2K compliant. It is my belief that earlier versions were also Y2K compliant. Libpng only has three year fields. One is a 2-byte unsigned integer that @@ -3806,6 +3833,11 @@ the first widely used release: 1.2.6rc1-5 13 10206 12.so.0.1.2.6rc1-5 1.0.16 10 10016 10.so.0.1.0.16 1.2.6 13 10206 12.so.0.1.2.6 + 1.2.7beta1-2 13 10207 12.so.0.1.2.7beta1-2 + 1.0.17rc1 10 10017 12.so.0.1.0.17rc1 + 1.2.7rc1 13 10207 12.so.0.1.2.7rc1 + 1.0.17 10 10017 12.so.0.1.0.17 + 1.2.7 13 10207 12.so.0.1.2.7 Henceforth the source version will match the shared-library minor and patch numbers; the shared-library major version number will be @@ -3822,7 +3854,7 @@ libpngpf(3), png(5) .LP .IR libpng : .IP -ftp://ftp.uu.net/graphics/png +http://libpng.sourceforge.net (follow the [DOWNLOAD] link) http://www.libpng.org/pub/png .LP @@ -3832,8 +3864,6 @@ http://www.libpng.org/pub/png .I libpng or at .br -ftp://ftp.uu.net/pub/archiving/zip/zlib -.br ftp://ftp.info-zip.org/pub/infozip/zlib .LP @@ -3863,13 +3893,14 @@ possible without all of you. Thanks to Frank J. T. Wojcik for helping with the documentation. -Libpng version 1.2.6 - August 15, 2004: +Libpng version 1.2.7 - September 12, 2004: Initially created in 1995 by Guy Eric Schalnat, then of Group 42, Inc. Currently maintained by Glenn Randers-Pehrson (glennrp@users.sourceforge.net). Supported by the PNG development group .br -(png-implement@ccrc.wustl.edu). +png-implement@ccrc.wustl.edu (subscription required; write to +majordomo@ccrc.wustl.edu with "subscribe png-implement" in the message). .SH COPYRIGHT NOTICE, DISCLAIMER, and LICENSE: @@ -3880,7 +3911,7 @@ included in the libpng distribution, the latter shall prevail.) If you modify libpng you may insert additional notices immediately following this sentence. -libpng version 1.2.6, August 15, 2004, is +libpng version 1.2.6, September 12, 2004, is Copyright (c) 2004 Glenn Randers-Pehrson, and is distributed according to the same disclaimer and license as libpng-1.2.5 with the following individual added to the list of Contributing Authors @@ -3979,7 +4010,7 @@ certification mark of the Open Source Initiative. Glenn Randers-Pehrson glennrp@users.sourceforge.net -August 15, 2004 +September 12, 2004 .\" end of man page