[devel] Document png_set_expand_16, correct transformation table.
This commit is contained in:
John Bowler
Glenn Randers-Pehrson
parent
3aa94d69fb
commit
63d059ab0b
@ -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
|
||||
|
||||
107
libpng.3
107
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user