[devel] Revised commentary about png_set_alpha_mode() to make it clearer
that this only affects how composited pixels are returned to the calling
application; they don't affect the pixels that are written to a PNG file.
diff --git a/png.h b/png.h
index 255673e..418c317 100644
--- a/png.h
+++ b/png.h
@@ -1118,15 +1118,19 @@
#ifdef PNG_READ_ALPHA_MODE_SUPPORTED
/* How the alpha channel is interpreted - this affects how the color channels of
- * a PNG file are output when an alpha channel, or tRNS chunk is a palette file,
- * is present.
+ * a PNG file are returned when an alpha channel, or tRNS chunk in a palette
+ * file, is present.
*
- * The default is to output data according to the PNG specification: the alpha
+ * This has no effect on the way pixels are written into a PNG output
+ * datastream. The color samples in a PNG datastream are never premultiplied
+ * with the alpha samples.
+ *
+ * The default is to return data according to the PNG specification: the alpha
* channel is a linear measure of the contribution of the pixel to the
- * corresponding output pixel. The gamma encoded color channels must be scaled
- * according to the contribution and to do this it is necessary to undo the
- * encoding, scale the color values, perform the composition and reencode the
- * values. This is the 'PNG' format.
+ * corresponding composited pixel. The gamma encoded color channels must be
+ * scaled according to the contribution and to do this it is necessary to undo
+ * the encoding, scale the color values, perform the composition and reencode
+ * the values. This is the 'PNG' mode.
*
* The alternative is to 'associate' the alpha with the color information by
* storing color channel values that have been scaled by the alpha. The
