From 63d059ab0b69d545074cb7c48e5c1203c5ed8b4e Mon Sep 17 00:00:00 2001 From: John Bowler Date: Sat, 12 Feb 2011 09:03:44 -0600 Subject: [PATCH] [devel] Document png_set_expand_16, correct transformation table. --- libpng-manual.txt | 115 +++++++++++++++++++++++++++++----------------- libpng.3 | 107 ++++++++++++++++++++++++++++-------------- 2 files changed, 146 insertions(+), 76 deletions(-) diff --git a/libpng-manual.txt b/libpng-manual.txt index 8886ef1b9..86f46fd60 100644 --- a/libpng-manual.txt +++ b/libpng-manual.txt @@ -1161,13 +1161,13 @@ 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 (color_type == PNG_COLOR_TYPE_GRAY && - bit_depth < 8) png_set_expand_gray_1_2_4_to_8(png_ptr); - if (png_get_valid(png_ptr, info_ptr, PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_ptr); -These three functions are actually aliases for png_set_expand(), added + 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. @@ -1175,42 +1175,13 @@ 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.2beta01, not all possible expansions are supported. +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. -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 - - 31 - - 0 1 - - 0T - - 0O - - 2 GX - - 2T - - 2O - - 3 1 - - 3T - - 3O - - 4A T - - 4O - - 6A GX TX TX - - 6O GX TX - - -Within the matrix, - "-" means the transformation is not supported. - "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 - "G" means the transformation is obtained by - png_set_gray_to_rgb(). - "P" means the transformation is obtained by - png_set_expand_palette_to_rgb(). - "T" means the transformation is obtained by - png_set_tRNS_to_alpha(). + 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. @@ -1226,6 +1197,68 @@ it with the background, so that's what you should probably do): if (color_type & PNG_COLOR_MASK_ALPHA) png_set_strip_alpha(png_ptr); +See below for png_set_background(), which does the correct composition on a +single opaque color. This is probably what you should do in all cases rather +than use png_set_strip_alpha() - unless you know for sure that it is the wrong +thing to do. + +As of libpng version 1.5.2, almost all useful expansions are supported, the +major ommissions are convertion of grayscale to indexed images (which can be +done trivially in the application) and convertion 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() or + png_set_rgb_to_Y(). + "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(). + "8" means the transformation is obtained by png_set_strip_16(). + "6" means the transformation is obtained by png_set_expand_16(). + +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 @@ -1352,7 +1385,7 @@ Libpng approximates this with integers scaled by 32768: The calculation is done in a linear colorspace, if the image gamma can be determined. -If you have a grayscale and you are using png_set_expand_depth(), +If you have a grayscale and you are using png_set_expand_gray_1_2_4_to_8(), png_set_expand(), or png_set_gray_to_rgb to change to truecolor or to a higher bit-depth, you must either supply the background color as a gray value at the original file bit-depth (need_expand = 1) or else supply the @@ -3623,7 +3656,7 @@ 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 palette images. +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 diff --git a/libpng.3 b/libpng.3 index 64b66aff8..7c2ffbacd 100644 --- a/libpng.3 +++ b/libpng.3 @@ -576,6 +576,10 @@ libpng \- Portable Network Graphics (PNG) Reference Library 1.5.2beta01 \fI\fB +\fBvoid png_set_expand_16 (png_structp \fIpng_ptr\fP\fB);\fP + +\fI\fB + \fBvoid png_set_expand_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP \fI\fB @@ -2094,42 +2098,13 @@ 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.2beta01, not all possible expansions are supported. +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. -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 - - 31 - - 0 1 - - 0T - - 0O - - 2 GX - - 2T - - 2O - - 3 1 - - 3T - - 3O - - 4A T - - 4O - - 6A GX TX TX - - 6O GX TX - - -Within the matrix, - "-" means the transformation is not supported. - "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 - "G" means the transformation is obtained by - png_set_gray_to_rgb(). - "P" means the transformation is obtained by - png_set_expand_palette_to_rgb(). - "T" means the transformation is obtained by - png_set_tRNS_to_alpha(). + 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. @@ -2145,6 +2120,68 @@ it with the background, so that's what you should probably do): if (color_type & PNG_COLOR_MASK_ALPHA) png_set_strip_alpha(png_ptr); +See below for png_set_background(), which does the correct composition on a +single opaque color. This is probably what you should do in all cases rather +than use png_set_strip_alpha() - unless you know for sure that it is the wrong +thing to do. + +As of libpng version 1.5.2, almost all useful expansions are supported, the +major ommissions are convertion of grayscale to indexed images (which can be +done trivially in the application) and convertion 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() or + png_set_rgb_to_Y(). + "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(). + "8" means the transformation is obtained by png_set_strip_16(). + "6" means the transformation is obtained by png_set_expand_16(). + +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