summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/FindPhoto.337
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,