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
127

DESCRIPTION

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

PORTABILITY

244       In  Tk 8.3 and earlier, Tk_PhotoPutBlock and Tk_PhotoPutZoomedBlock had
245       different signatures. If you want to compile code  that  uses  the  old
246       interface  against  8.4 without updating your code, compile it with the
247       flag  -DUSE_COMPOSITELESS_PHOTO_PUT_BLOCK.   Code  linked  using  Stubs
248       against older versions of Tk will continue to work.
249
250       In Tk 8.4, Tk_PhotoPutBlock, Tk_PhotoPutZoomedBlock, Tk_PhotoExpand and │
251       Tk_PhotoSetSize did not take an interp argument or  return  any  result │
252       code.   If  insufficient  memory  was  available for an image, Tk would │
253       panic.  This behaviour is still supported if you compile your extension │
254       with  the  additional  flag  -DUSE_PANIC_ON_PHOTO_ALLOC_FAILURE.   Code │
255       linked using Stubs against older versions of Tk will continue to work.
256
257

CREDITS

259       The code for the photo image type  was  developed  by  Paul  Mackerras,
260       based on his earlier photo widget code.
261
262

KEYWORDS

264       photo, image
265
266
267
268Tk                                    8.0                      Tk_FindPhoto(3)
Impressum