Proposed fix for 22ace0d494 (documentation only)

1 files changed, 32 insertions, 5 deletions

diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3
index e4d83f0..3f6b919 100644
--- a/doc/FindPhoto.3
+++ b/doc/FindPhoto.3
@@ -130,14 +130,23 @@ The \fIpixelPtr\fR field points to the first pixel, that is, the
 top-left pixel in the block.
 The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the
 block of pixels.  The \fIpixelSize\fR field specifies the address
-difference between two horizontally adjacent pixels.  Often it is 3
-or 4, but it can have any value.  The \fIpitch\fR field specifies the
+difference between two horizontally adjacent pixels.  It should be 4 for
+RGB and 2 for grayscale image data.  Other values are possible, if the
+offsets in the \fIoffset\fR array are adjusted accordingly (e.g. for
+red, green and blue data stored in different planes).  Using such a
+layout is strongly discouraged, though. Due to a bug, it might not work
+correctly if an alpha channel is provided. (see the \fBBUGS\fR section
+below). The \fIpitch\fR field specifies the
 address difference between two vertically adjacent pixels.  The
 \fIoffset\fR array contains the offsets from the address of a pixel
 to the addresses of the bytes containing the red, green, blue and alpha
-(transparency) components.  These are normally 0, 1, 2 and 3, but can
-have other values, e.g., for images that are stored as separate red,
-green and blue planes.
+(transparency) components.  If the offsets for red, green and blue are
+equal, the image is interpreted as grayscale. If they differ, RGB data
+is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data
+and 0, 0, 0, 1 for grayscale.  It is possible to provide image data
+without an alpha channel by setting the offset for alpha to a negative
+value and adjusting the \fIpixelSize\fR field accordingly. This use is
+discouraged, though (see the \fBBUGS\fR section below).
 .PP
 The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a
 compositing rule that says what to do with transparent pixels.  The
@@ -248,6 +257,24 @@ memory was available for an image, Tk would panic.  This behaviour is
 still supported if you compile your extension with the additional flag
 -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE.  Code linked using Stubs against
 older versions of Tk will continue to work.
+.SH BUGS
+The \fBTk_PhotoImageBlock\fR structure used to provide image data to
+\fBTk_PhotoPutBlock\fR promises great flexibility in the layout of the
+data (e.g. separate planes for the red, green, blue and alpha
+channels).  Unfortunately, the implementation fails to hold this
+promise.  The problem is that the \fIpixelSize\fR field is
+(incorrectly) used to determine wehter the image has an alpha channel.
+Currently, if the offset for the alpha channel is greater or equal than
+\fIpixelSize\fR, \fBtk_PhotoPutblock\fR assumes no alpha data is
+present and makes the image fully opaque.  This means that for layouts
+where the channels are separate (or any other exotic layout where
+\fIpixelSize\fR has to be smaller than the alpha offset), the alpha
+channel will not be read correctly.  In order to be on the safe side
+if this issue will be corrected in a future release, it is strongly
+recommended you always provide alpha data - even if the image has no
+transparency - and only use the "standard" layout with a
+\fIpixelSize\fR of 2 for grayscale and 4 for RGB data with
+\fIoffset\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively.
 .SH CREDITS
 .PP
 The code for the photo image type was developed by Paul Mackerras,