X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5b02c8a11f0e0d284eff32cfde1fcd2a4b2e659d..47e59154157bb013ce255a4efa7a615574c974f7:/src/png/libpng.txt diff --git a/src/png/libpng.txt b/src/png/libpng.txt index 0324715bb2..4dec2dd3ae 100644 --- a/src/png/libpng.txt +++ b/src/png/libpng.txt @@ -1,6 +1,6 @@ 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 @@ -37,19 +37,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 @@ -82,7 +86,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. - II. Structures There are two main structures that are important to libpng, png_struct @@ -397,6 +400,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 @@ -761,14 +767,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 @@ -853,6 +859,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: @@ -1997,6 +2013,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(). + The low-level write interface If you are going the low-level route instead, you are now ready to @@ -2808,7 +2827,7 @@ For more extensive examples of runtime querying, enabling and disabling of optimized features, see contrib/gregbook/readpng2.c in the libpng source-code distribution. -VI. MNG support +VII. MNG support The MNG specification (available at http://www.libpng.org/pub/mng) allows certain extensions to PNG for PNG images that are embedded in MNG datastreams. @@ -2833,7 +2852,7 @@ or any other MNG chunks; your application must provide its own support for them. You may wish to consider using libmng (available at http://www.libmng.com) instead. -VII. Changes to Libpng from version 0.88 +VIII. Changes to Libpng from version 0.88 It should be noted that versions of libpng later than 0.96 are not distributed by the original libpng author, Guy Schalnat, nor by @@ -2882,15 +2901,15 @@ application: png_uint_32 application_vn = PNG_LIBPNG_VER; -VII. Y2K Compliance in libpng +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