1Tk_FindPhoto(3) Tk Library Procedures Tk_FindPhoto(3)
2______________________________________________________________________________
6
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
13 #include <tk.h>
14 Tk_PhotoHandle
16 Tk_FindPhoto(interp, imageName)
17 int │
19 Tk_PhotoPutBlock(interp, handle, blockPtr, x, y, width, height,compRule)│
20 int │
22 Tk_PhotoPutZoomedBlock(interp, handle, blockPtr, x, y, width, height,zoomX, zoomY, subsampleX, subsampleY, compRule)│
23 int
25 Tk_PhotoGetImage(handle, blockPtr)
26 void
28 Tk_PhotoBlank(handle)
29 int │
31 Tk_PhotoExpand(interp, handle, width, height) │
32 void
34 Tk_PhotoGetSize(handle, widthPtr, heightPtr)
35 int │
37 Tk_PhotoSetSize(interp. handle, width, height) │
38
40 Tcl_Interp *interp (in) Interpreter in which image
41 was created and in which
42 error reporting is to be
43 done.
44 const char *imageName (in) Name of the photo image.
46 Tk_PhotoHandle handle (in) Opaque handle identifying
48 the photo image to be
49 affected.
50 Tk_PhotoImageBlock *blockPtr (in) Specifies the address and
52 storage layout of image
53 data.
54 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 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 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 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 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 int *widthPtr (out) Pointer to location in
99 which to store the image
100 width.
101 int *heightPtr (out) Pointer to location in
103 which to store the image
104 height.
105 int subsampleX (in) Specifies the subsampling
107 factor in the X direction
108 for input image data.
109 int subsampleY (in) Specifies the subsampling
111 factor in the Y direction
112 for input image data.
113 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 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
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 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 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 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 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 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 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 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 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 Tk_PhotoBlank blanks the entire area of the photo image. Blank areas
211 of a photo image are transparent.
212 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 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 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 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 Tk_PhotoGetSize returns the dimensions of the image in *widthPtr and
240 *heightPtr.
241
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 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
259 The code for the photo image type was developed by Paul Mackerras,
260 based on his earlier photo widget code.
261
264 photo, image
265Tk 8.0 Tk_FindPhoto(3)