[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)
|
if (color_type == PNG_COLOR_TYPE_PALETTE)
|
||||||
png_set_palette_to_rgb(png_ptr);
|
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,
|
if (png_get_valid(png_ptr, info_ptr,
|
||||||
PNG_INFO_tRNS)) png_set_tRNS_to_alpha(png_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
|
in libpng version 1.0.4, with the function names expanded to improve code
|
||||||
readability. In some future version they may actually do different
|
readability. In some future version they may actually do different
|
||||||
things.
|
things.
|
||||||
@ -1175,42 +1175,13 @@ things.
|
|||||||
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
|
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.
|
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
|
if (bit_depth < 16)
|
||||||
indexed with depth<8, other numerals represent the color type, "T" means
|
png_set_expand_16(png_ptr);
|
||||||
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().
|
|
||||||
|
|
||||||
PNG can have files with 16 bits per channel. If you only can handle
|
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.
|
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)
|
if (color_type & PNG_COLOR_MASK_ALPHA)
|
||||||
png_set_strip_alpha(png_ptr);
|
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
|
In PNG files, the alpha channel in an image
|
||||||
is the level of opacity. If you need the alpha channel in an image to
|
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
|
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
|
The calculation is done in a linear colorspace, if the image gamma
|
||||||
can be determined.
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
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
|
\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
|
\fBvoid png_set_expand_gray_1_2_4_to_8 (png_structp \fIpng_ptr\fP\fB);\fP
|
||||||
|
|
||||||
\fI\fB
|
\fI\fB
|
||||||
@ -2094,42 +2098,13 @@ things.
|
|||||||
As of libpng version 1.2.9, png_set_expand_gray_1_2_4_to_8() was
|
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.
|
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
|
if (bit_depth < 16)
|
||||||
indexed with depth<8, other numerals represent the color type, "T" means
|
png_set_expand_16(png_ptr);
|
||||||
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().
|
|
||||||
|
|
||||||
PNG can have files with 16 bits per channel. If you only can handle
|
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.
|
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)
|
if (color_type & PNG_COLOR_MASK_ALPHA)
|
||||||
png_set_strip_alpha(png_ptr);
|
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
|
In PNG files, the alpha channel in an image
|
||||||
is the level of opacity. If you need the alpha channel in an image to
|
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
|
be the level of transparency instead of opacity, you can invert the
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user