[devel] Document png_set_expand_16, correct transformation table.
diff --git a/libpng.3 b/libpng.3
index 64b66af..7c2ffba 100644
--- a/libpng.3
+++ b/libpng.3
@@ -576,6 +576,10 @@
\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 @@
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 @@
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
