1Tk_FindPhoto(3)              Tk Library Procedures             Tk_FindPhoto(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_FindPhoto,  Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoGetIm‐
9       age, Tk_PhotoBlank, Tk_PhotoExpand, Tk_PhotoGetSize, Tk_PhotoSetSize  -
10       manipulate the image data stored in a photo image.
11

SYNOPSIS

13       #include <tk.h>
14
15       Tk_PhotoHandle
16       Tk_FindPhoto(interp, imageName)
17
18       int
19       Tk_PhotoPutBlock(interp, handle, blockPtr, x, y, width, height,compRule)
20
21       int
22       Tk_PhotoPutZoomedBlock(interp, handle, blockPtr, x, y, width, height,zoomX, zoomY, subsampleX, subsampleY, compRule)
23
24       int
25       Tk_PhotoGetImage(handle, blockPtr)
26
27       void
28       Tk_PhotoBlank(handle)
29
30       int
31       Tk_PhotoExpand(interp, handle, width, height)
32
33       void
34       Tk_PhotoGetSize(handle, widthPtr, heightPtr)
35
36       int
37       Tk_PhotoSetSize(interp. handle, width, height)
38

ARGUMENTS

40       Tcl_Interp *interp (in)                      Interpreter in which image
41                                                    was created and  in  which
42                                                    error  reporting  is to be
43                                                    done.
44
45       const char *imageName (in)                   Name of the photo image.
46
47       Tk_PhotoHandle handle (in)                   Opaque handle  identifying
48                                                    the   photo  image  to  be
49                                                    affected.
50
51       Tk_PhotoImageBlock *blockPtr (in)            Specifies the address  and
52                                                    storage  layout  of  image
53                                                    data.
54
55       int x (in)                                   Specifies the X coordinate
56                                                    where  the top-left corner
57                                                    of  the  block  is  to  be
58                                                    placed within the image.
59
60       int y (in)                                   Specifies the Y coordinate
61                                                    where the top-left  corner
62                                                    of  the  block  is  to  be
63                                                    placed within the image.
64
65       int width (in)                               Specifies the width of the
66                                                    image  area to be affected
67                                                    (for Tk_PhotoPutBlock)  or
68                                                    the  desired  image  width
69                                                    (for  Tk_PhotoExpand   and
70                                                    Tk_PhotoSetSize).
71
72       int compRule (in)                            Specifies  the compositing
73                                                    rule used  when  combining
74                                                    transparent  pixels  in  a
75                                                    block of data with a photo
76                                                    image.   Must  be  one  of
77                                                    TK_PHOTO_COMPOSITE_OVERLAY
78                                                    (which  puts  the block of
79                                                    data over the top  of  the
80                                                    existing photo image, with
81                                                    the   previous    contents
82                                                    showing   through  in  the
83                                                    transparent    bits)    or
84                                                    TK_PHOTO_COMPOSITE_SET
85                                                    (which discards the exist‐
86                                                    ing  photo  image contents
87                                                    in the  rectangle  covered
88                                                    by the data block.)
89
90       int height (in)                              Specifies  the  height  of
91                                                    the  image  area   to   be
92                                                    affected (for Tk_PhotoPut‐
93                                                    Block)  or   the   desired
94                                                    image  height (for Tk_Pho‐
95                                                    toExpand and  Tk_PhotoSet‐
96                                                    Size).
97
98       int *widthPtr (out)                          Pointer   to  location  in
99                                                    which to store  the  image
100                                                    width.
101
102       int *heightPtr (out)                         Pointer   to  location  in
103                                                    which to store  the  image
104                                                    height.
105
106       int subsampleX (in)                          Specifies  the subsampling
107                                                    factor in the X  direction
108                                                    for input image data.
109
110       int subsampleY (in)                          Specifies  the subsampling
111                                                    factor in the Y  direction
112                                                    for input image data.
113
114       int zoomX (in)                               Specifies  the zoom factor
115                                                    to be  applied  in  the  X
116                                                    direction  to pixels being
117                                                    written   to   the   photo
118                                                    image.
119
120       int zoomY (in)                               Specifies  the zoom factor
121                                                    to be  applied  in  the  Y
122                                                    direction  to pixels being
123                                                    written   to   the   photo
124                                                    image.
125______________________________________________________________________________
126

DESCRIPTION

128       Tk_FindPhoto  returns  an opaque handle that is used to identify a par‐
129       ticular photo image to the other procedures.  The parameter is the name
130       of  the  image,  that  is, the name specified to the image create photo
131       command, or assigned by that command if no name was specified.  If ima‐
132       geName  does  not  exist  or is not a photo image, Tk_FindPhoto returns
133       NULL.
134
135       Tk_PhotoPutBlock is used to supply blocks of  image  data  to  be  dis‐
136       played.   The  call affects an area of the image of size width x height
137       pixels, with its top-left corner at coordinates (x,y).  All  of  width,
138       height,  x, and y must be non-negative.  If part of this area lies out‐
139       side the current bounds of the image, the image  will  be  expanded  to
140       include  the area, unless the user has specified an explicit image size
141       with the  -width  and/or  -height  widget  configuration  options  (see
142       photo(n));  in  that  case  the  area  is silently clipped to the image
143       boundaries.
144
145       The block parameter is a pointer  to  a  Tk_PhotoImageBlock  structure,
146       defined as follows:
147              typedef struct {
148                  unsigned char *pixelPtr;
149                  int width;
150                  int height;
151                  int pitch;
152                  int pixelSize;
153                  int offset[4];
154              } Tk_PhotoImageBlock;
155       The  pixelPtr  field  points  to the first pixel, that is, the top-left
156       pixel in the block.  The width and height fields specify the dimensions
157       of the block of pixels.  The pixelSize field specifies the address dif‐
158       ference between two horizontally adjacent pixels.  It should be  4  for
159       RGB  and 2 for grayscale image data.  Other values are possible, if the
160       offsets in the offset array are adjusted  accordingly  (e.g.  for  red,
161       green  and  blue data stored in different planes).  Using such a layout
162       is strongly discouraged, though. Due to a bug, it might not  work  cor‐
163       rectly  if  an alpha channel is provided. (see the BUGS section below).
164       The pitch field specifies the address difference between two vertically
165       adjacent  pixels.   The  offset  array  contains  the  offsets from the
166       address of a pixel to the addresses of the bytes  containing  the  red,
167       green,  blue  and  alpha (transparency) components.  If the offsets for
168       red, green and blue are equal, the image is interpreted  as  grayscale.
169       If they differ, RGB data is assumed. Normally the offsets will be 0, 1,
170       2, 3 for RGB data and 0, 0, 0, 1 for grayscale.  It is possible to pro‐
171       vide  image  data  without  an  alpha channel by setting the offset for
172       alpha to a negative value and adjusting  the  pixelSize  field  accord‐
173       ingly. This use is discouraged, though (see the BUGS section below).
174
175       The compRule parameter to Tk_PhotoPutBlock specifies a compositing rule
176       that says what to do with transparent pixels.  The value  TK_PHOTO_COM‐
177       POSITE_OVERLAY  says  that  the  previous  contents  of the photo image
178       should show through, and the value TK_PHOTO_COMPOSITE_SET says that the
179       previous  contents of the photo image should be completely ignored, and
180       the values from the block be copied directly across.  The  behavior  in
181       Tk8.3  and  earlier was equivalent to having TK_PHOTO_COMPOSITE_OVERLAY
182       as a compositing rule.
183
184       The value given for the width and height parameters to Tk_PhotoPutBlock
185       do  not  have  to correspond to the values specified in block.  If they
186       are smaller, Tk_PhotoPutBlock extracts a sub-block from the image  data
187       supplied.   If  they  are  larger,  the data given are replicated (in a
188       tiled fashion) to fill the specified area.  These rules  operate  inde‐
189       pendently in the horizontal and vertical directions.
190
191       Tk_PhotoPutBlock  normally returns TCL_OK, though if it cannot allocate
192       sufficient memory to hold the resulting image,  TCL_ERROR  is  returned
193       instead  and,  if  the interp argument is non-NULL, an error message is
194       placed in the interpreter's result.
195
196       Tk_PhotoPutZoomedBlock works  like  Tk_PhotoPutBlock  except  that  the
197       image  can be reduced or enlarged for display.  The subsampleX and sub‐
198       sampleY parameters allow the size of the image to be reduced by subsam‐
199       pling.   Tk_PhotoPutZoomedBlock  will  use  only  pixels from the input
200       image whose X coordinates are multiples  of  subsampleX,  and  whose  Y
201       coordinates  are  multiples  of  subsampleY.   For example, an image of
202       512x512 pixels can be reduced to 256x256 by setting subsampleX and sub‐
203       sampleY to 2.
204
205       The  zoomX and zoomY parameters allow the image to be enlarged by pixel
206       replication.  Each pixel of the (possibly subsampled) input image  will
207       be  written  to  a block zoomX pixels wide and zoomY pixels high of the
208       displayed image.  Subsampling and zooming can be used together for spe‐
209       cial effects.
210
211       Tk_PhotoGetImage can be used to retrieve image data from a photo image.
212       Tk_PhotoGetImage fills in the structure  pointed  to  by  the  blockPtr
213       parameter with values that describe the address and layout of the image
214       data that the photo image has stored internally.  The values are  valid
215       until the image is destroyed or its size is changed.
216
217       It  is  possible to modify an image by writing directly to the data the
218       pixelPtr field points to. The size of the image cannot be changed  this
219       way,  though.   Also, changes made by writing directly to pixelPtr will
220       not be immediately visible, but only after a call to Tk_ImageChanged or
221       after an event that causes the interested widgets to redraw themselves.
222       For these reasons usually it is preferable to make changes to a copy of
223       the  image data and write it back with Tk_PhotoPutBlock or Tk_PhotoPut‐
224       ZoomedBlock.
225
226       Tk_PhotoGetImage returns 1 for  compatibility  with  the  corresponding
227       procedure in the old photo widget.
228
229       Tk_PhotoBlank  blanks  the entire area of the photo image.  Blank areas
230       of a photo image are transparent.
231
232       Tk_PhotoExpand requests that the widget's image be expanded  to  be  at
233       least  width  x  height  pixels  in  size.  The width and/or height are
234       unchanged if the user has specified an explicit image width  or  height
235       with the -width and/or -height configuration options, respectively.  If
236       the image data are being supplied in many  small  blocks,  it  is  more
237       efficient  to  use  Tk_PhotoExpand  or Tk_PhotoSetSize at the beginning
238       rather than allowing the image to expand in many  small  increments  as
239       image blocks are supplied.
240
241       Tk_PhotoExpand  normally  returns  TCL_OK, though if it cannot allocate
242       sufficient memory to hold the resulting image,  TCL_ERROR  is  returned
243       instead  and,  if  the interp argument is non-NULL, an error message is
244       placed in the interpreter's result.
245
246       Tk_PhotoSetSize specifies the size of the image, as  if  the  user  had
247       specified  the  given width and height values to the -width and -height
248       configuration options.  A value of zero for width or  height  does  not
249       change  the  image's width or height, but allows the width or height to
250       be changed by subsequent calls to Tk_PhotoPutBlock,  Tk_PhotoPutZoomed‐
251       Block or Tk_PhotoExpand.
252
253       Tk_PhotoSetSize  normally  returns TCL_OK, though if it cannot allocate
254       sufficient memory to hold the resulting image,  TCL_ERROR  is  returned
255       instead  and,  if  the interp argument is non-NULL, an error message is
256       placed in the interpreter's result.
257
258       Tk_PhotoGetSize returns the dimensions of the image  in  *widthPtr  and
259       *heightPtr.
260

PORTABILITY

262       In  Tk 8.3 and earlier, Tk_PhotoPutBlock and Tk_PhotoPutZoomedBlock had
263       different signatures. If you want to compile code  that  uses  the  old
264       interface  against  8.4 without updating your code, compile it with the
265       flag  -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK.   Code  linked  using  Stubs
266       against older versions of Tk will continue to work.
267
268       In Tk 8.4, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoExpand and
269       Tk_PhotoSetSize did not take an interp argument or  return  any  result
270       code.   If  insufficient  memory  was  available for an image, Tk would
271       panic.  This behaviour is still supported if you compile your extension
272       with  the  additional  flag  -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE.   Code
273       linked using Stubs against older versions of Tk will continue to work.
274

BUGS

276       The Tk_PhotoImageBlock structure used to provide image data to  Tk_Pho‐
277       toPutBlock  promises  great flexibility in the layout of the data (e.g.
278       separate planes for the red, green, blue and alpha channels).  Unfortu‐
279       nately,  the implementation fails to hold this promise.  The problem is
280       that the pixelSize field is (incorrectly) used to determine whether the
281       image  has  an  alpha  channel.  Currently, if the offset for the alpha
282       channel is greater or equal than pixelSize, tk_PhotoPutblock assumes no
283       alpha  data  is  present  and makes the image fully opaque.  This means
284       that for layouts where the channels are separate (or any  other  exotic
285       layout  where  pixelSize  has to be smaller than the alpha offset), the
286       alpha channel will not be read correctly.  In order to be on  the  safe
287       side  if  this  issue  will  be  corrected  in  a future release, it is
288       strongly recommended you always provide alpha data - even if the  image
289       has  no transparency - and only use the "standard" layout with a pixel‐
290       Size of 2 for grayscale and 4 for RGB data with offsets of 0, 0,  0,  1
291       or 0, 1, 2, 3 respectively.
292

CREDITS

294       The  code  for  the  photo  image type was developed by Paul Mackerras,
295       based on his earlier photo widget code.
296

KEYWORDS

298       photo, image
299
300
301
302Tk                                    8.0                      Tk_FindPhoto(3)
Impressum