|
4 | 4 | '\" |
5 | 5 | '\" See the file "license.terms" for information on usage and redistribution |
6 | 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
7 | | -'\" |
| 7 | +'\" |
8 | 8 | '\" Author: Paul Mackerras ([email protected]), |
9 | 9 | '\" Department of Computer Science, |
10 | 10 | '\" Australian National University. |
@@ -99,8 +99,8 @@ being written to the photo image. |
99 | 99 | particular photo image to the other procedures. The parameter is the |
100 | 100 | name of the image, that is, the name specified to the \fBimage create |
101 | 101 | photo\fR command, or assigned by that command if no name was specified. |
102 | | -If \fIimageName\fR does not exist or is not a photo image, |
103 | | -\fBTk_FindPhoto\fR returns NULL. |
| 102 | +If \fIimageName\fR does not exist or is not a photo image, |
| 103 | +\fBTk_FindPhoto\fR returns NULL. |
104 | 104 | .PP |
105 | 105 | \fBTk_PhotoPutBlock\fR is used to supply blocks of image data to be |
106 | 106 | displayed. The call affects an area of the image of size |
@@ -130,14 +130,23 @@ The \fIpixelPtr\fR field points to the first pixel, that is, the |
130 | 130 | top-left pixel in the block. |
131 | 131 | The \fIwidth\fR and \fIheight\fR fields specify the dimensions of the |
132 | 132 | block of pixels. The \fIpixelSize\fR field specifies the address |
133 | | -difference between two horizontally adjacent pixels. Often it is 3 |
134 | | -or 4, but it can have any value. The \fIpitch\fR field specifies the |
| 133 | +difference between two horizontally adjacent pixels. It should be 4 for |
| 134 | +RGB and 2 for grayscale image data. Other values are possible, if the |
| 135 | +offsets in the \fIoffset\fR array are adjusted accordingly (e.g. for |
| 136 | +red, green and blue data stored in different planes). Using such a |
| 137 | +layout is strongly discouraged, though. Due to a bug, it might not work |
| 138 | +correctly if an alpha channel is provided. (see the \fBBUGS\fR section |
| 139 | +below). The \fIpitch\fR field specifies the |
135 | 140 | address difference between two vertically adjacent pixels. The |
136 | 141 | \fIoffset\fR array contains the offsets from the address of a pixel |
137 | 142 | to the addresses of the bytes containing the red, green, blue and alpha |
138 | | -(transparency) components. These are normally 0, 1, 2 and 3, but can |
139 | | -have other values, e.g., for images that are stored as separate red, |
140 | | -green and blue planes. |
| 143 | +(transparency) components. If the offsets for red, green and blue are |
| 144 | +equal, the image is interpreted as grayscale. If they differ, RGB data |
| 145 | +is assumed. Normally the offsets will be 0, 1, 2, 3 for RGB data |
| 146 | +and 0, 0, 0, 1 for grayscale. It is possible to provide image data |
| 147 | +without an alpha channel by setting the offset for alpha to a negative |
| 148 | +value and adjusting the \fIpixelSize\fR field accordingly. This use is |
| 149 | +discouraged, though (see the \fBBUGS\fR section below). |
141 | 150 | .PP |
142 | 151 | The \fIcompRule\fR parameter to \fBTk_PhotoPutBlock\fR specifies a |
143 | 152 | compositing rule that says what to do with transparent pixels. The |
@@ -184,16 +193,16 @@ that describe the address and layout of the image data that the |
184 | 193 | photo image has stored internally. The values are valid |
185 | 194 | until the image is destroyed or its size is changed. |
186 | 195 | .PP |
187 | | -It is possible to modify an image by writing directly to the data |
| 196 | +It is possible to modify an image by writing directly to the data |
188 | 197 | the \fIpixelPtr\fR field points to. The size of the image cannot be |
189 | 198 | changed this way, though. |
190 | | -Also, changes made by writing directly to \fIpixelPtr\fR will not be |
191 | | -immediately visible, but only after a call to |
192 | | -\fBTk_ImageChanged\fR or after an event that causes the interested |
| 199 | +Also, changes made by writing directly to \fIpixelPtr\fR will not be |
| 200 | +immediately visible, but only after a call to |
| 201 | +\fBTk_ImageChanged\fR or after an event that causes the interested |
193 | 202 | widgets to redraw themselves. |
194 | | -For these reasons usually it is preferable to make changes to |
195 | | -a copy of the image data and write it back with |
196 | | -\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. |
| 203 | +For these reasons usually it is preferable to make changes to |
| 204 | +a copy of the image data and write it back with |
| 205 | +\fBTk_PhotoPutBlock\fR or \fBTk_PhotoPutZoomedBlock\fR. |
197 | 206 | .PP |
198 | 207 | \fBTk_PhotoGetImage\fR returns 1 for compatibility with the |
199 | 208 | corresponding procedure in the old photo widget. |
@@ -248,6 +257,24 @@ memory was available for an image, Tk would panic. This behaviour is |
248 | 257 | still supported if you compile your extension with the additional flag |
249 | 258 | -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE. Code linked using Stubs against |
250 | 259 | older versions of Tk will continue to work. |
| 260 | +.SH BUGS |
| 261 | +The \fBTk_PhotoImageBlock\fR structure used to provide image data to |
| 262 | +\fBTk_PhotoPutBlock\fR promises great flexibility in the layout of the |
| 263 | +data (e.g. separate planes for the red, green, blue and alpha |
| 264 | +channels). Unfortunately, the implementation fails to hold this |
| 265 | +promise. The problem is that the \fIpixelSize\fR field is |
| 266 | +(incorrectly) used to determine whether the image has an alpha channel. |
| 267 | +Currently, if the offset for the alpha channel is greater or equal than |
| 268 | +\fIpixelSize\fR, \fBtk_PhotoPutblock\fR assumes no alpha data is |
| 269 | +present and makes the image fully opaque. This means that for layouts |
| 270 | +where the channels are separate (or any other exotic layout where |
| 271 | +\fIpixelSize\fR has to be smaller than the alpha offset), the alpha |
| 272 | +channel will not be read correctly. In order to be on the safe side |
| 273 | +if this issue will be corrected in a future release, it is strongly |
| 274 | +recommended you always provide alpha data - even if the image has no |
| 275 | +transparency - and only use the "standard" layout with a |
| 276 | +\fIpixelSize\fR of 2 for grayscale and 4 for RGB data with |
| 277 | +\fIoffset\fRs of 0, 0, 0, 1 or 0, 1, 2, 3 respectively. |
251 | 278 | .SH CREDITS |
252 | 279 | .PP |
253 | 280 | The code for the photo image type was developed by Paul Mackerras, |
|
0 commit comments