diff options
| -rw-r--r-- | doc/FindPhoto.3 | 37 |
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, |