1Photo(3) User Contributed Perl Documentation Photo(3)
2
6 Tk::Photo - Full-color images
7
9 $widget->Photo(?name??, options?)
10
12 A photo is an image whose pixels can display any color or be transpar‐
13 ent. A photo image is stored internally in full color (32 bits per
14 pixel), and is displayed using dithering if necessary. Image data for
15 a photo image can be obtained from a file or a string, or it can be
16 supplied from C code through a procedural interface. At present, only
17 GIF, XBM, XPM, BMP, JPEG, PNG and PPM/PGM formats are supported, but an
18 interface exists to allow additional image file formats to be added
19 easily. A photo image is transparent in regions where no image data
20 has been supplied or where it has been set transparent by the trans‐
21 parencySet subcommand.
22
24 Photos are created using the Photo method. Photo supports the follow‐
25 ing options:
26 -data => string
28 Specifies the contents of the image as a string. The string can
29 contain base64 encoded data or binary data. The format of the
30 string must be one of those for which there is an image file format
31 handler that will accept string data. If both the -data and -file
32 options are specified, the -file option takes precedence.
33 -format => format-name
35 Specifies the name of the file format for the data specified with
36 the -data or -file option.
37 -file => name
39 name gives the name of a file that is to be read to supply data for
40 the photo image. The file format must be one of those for which
41 there is an image file format handler that can read data.
42 -gamma => value
44 Specifies that the colors allocated for displaying this image in a
45 window should be corrected for a non-linear display with the speci‐
46 fied gamma exponent value. (The intensity produced by most CRT
47 displays is a power function of the input value, to a good approxi‐
48 mation; gamma is the exponent and is typically around 2). The
49 value specified must be greater than zero. The default value is
50 one (no correction). In general, values greater than one will make
51 the image lighter, and values less than one will make it darker.
52 -height => number
54 Specifies the height of the image, in pixels. This option is use‐
55 ful primarily in situations where the user wishes to build up the
56 contents of the image piece by piece. A value of zero (the
57 default) allows the image to expand or shrink vertically to fit the
58 data stored in it.
59 -palette => palette-spec
61 Specifies the resolution of the color cube to be allocated for dis‐
62 playing this image, and thus the number of colors used from the
63 colormaps of the windows where it is displayed. The palette-spec
64 string may be either a single decimal number, specifying the number
65 of shades of gray to use, or three decimal numbers separated by
66 slashes (/), specifying the number of shades of red, green and blue
67 to use, respectively. If the first form (a single number) is used,
68 the image will be displayed in monochrome (i.e., grayscale).
69 -width => number
71 Specifies the width of the image, in pixels. This option is use‐
72 ful primarily in situations where the user wishes to build up the
73 contents of the image piece by piece. A value of zero (the
74 default) allows the image to expand or shrink horizontally to fit
75 the data stored in it.
76
78 When a photo image is created, Tk also creates a new object. This
79 object supports the configure and cget methods described in Tk::options
80 which can be used to enquire and modify the options described above.
81 Those options that write data to the image generally expand the size of
83 the image, if necessary, to accommodate the data written to the image,
84 unless the user has specified non-zero values for the -width and/or
85 -height configuration options, in which case the width and/or height,
86 respectively, of the image will not be changed.
87 The following addition methods are available for photo images:
89 $image->blank
91 Blank the image; that is, set the entire image to have no data, so
92 it will be displayed as transparent, and the background of whatever
93 window it is displayed in will show through.
94 $image->copy(sourceImage ?,option value(s) ...?)
96 Copies a region from the image called $sourceImage (which must be a
97 photo image) to the image called $image, possibly with pixel zoom‐
98 ing and/or subsampling. If no options are specified, this method
99 copies the whole of $sourceImage into $image, starting at coordi‐
100 nates (0,0) in $image. The following options may be specified:
101 -from => x1, y1, ? ,x2, y2?
103 Specifies a rectangular sub-region of the source image to
104 be copied. (x1,y1) and (x2,y2) specify diagonally opposite
105 corners of the rectangle. If x2 and y2 are not specified,
106 the default value is the bottom-right corner of the source
107 image. The pixels copied will include the left and top
108 edges of the specified rectangle but not the bottom or
109 right edges. If the -from option is not given, the default
110 is the whole source image.
111 -to => x1, y1, ?, x2, y2?
113 Specifies a rectangular sub-region of the destination image
114 to be affected. (x1,y1) and (x2,y2) specify diagonally
115 opposite corners of the rectangle. If x2 and y2 are not
116 specified, the default value is (x1,y1) plus the size of
117 the source region (after subsampling and zooming, if speci‐
118 fied). If x2 and y2 are specified, the source region will
119 be replicated if necessary to fill the destination region
120 in a tiled fashion.
121 -shrink Specifies that the size of the destination image should be
123 reduced, if necessary, so that the region being copied into
124 is at the bottom-right corner of the image. This option
125 will not affect the width or height of the image if the
126 user has specified a non-zero value for the -width or
127 -height configuration option, respectively.
128 -zoom => x, y
130 Specifies that the source region should be magnified by a
131 factor of x in the X direction and y in the Y direction.
132 If y is not given, the default value is the same as x.
133 With this option, each pixel in the source image will be
134 expanded into a block of x x y pixels in the destination
135 image, all the same color. x and y must be greater than 0.
136 -subsample => x, y
138 Specifies that the source image should be reduced in size
139 by using only every xth pixel in the X direction and yth
140 pixel in the Y direction. Negative values will cause the
141 image to be flipped about the Y or X axes, respectively.
142 If y is not given, the default value is the same as x.
143 -compositingrule => rule
145 Specifies how transparent pixels in the source image are
146 combined with the destination image. When a compositing
147 rule of overlay is set, the old contents of the destination
148 image are visible, as if the source image were printed on a
149 piece of transparent film and placed over the top of the
150 destination. When a compositing rule of set is set, the
151 old contents of the destination image are discarded and the
152 source image is used as-is. The default compositing rule
153 is overlay.
154 $image->data(?option value(s), ...?)
156 Returns image data in the form of a string. The following options
157 may be specified:
158 -background => color
160 If the color is specified, the data will not contain any
161 transparency information. In all transparent pixels the
162 color will be replaced by the specified color.
163 -format => format-name
165 Specifies the name of the image file format handler to be
166 used. Specifically, this method searches for the first
167 handler whose name matches a initial substring of format-
168 name and which has the capability to read this image data.
169 If this option is not given, this method uses the first
170 handler that has the capability to read the image data.
171 -from => x1, y1, ?, x2, y2?
173 Specifies a rectangular region of $image to be returned.
174 If only x1 and y1 are specified, the region extends from
175 (x1,y1) to the bottom-right corner of $image. If all four
176 coordinates are given, they specify diagonally opposite
177 corners of the rectangular region, including x1,y1 and
178 excluding x2,y2. The default, if this option is not given,
179 is the whole image.
180 -grayscale
182 If this options is specified, the data will not contain
183 color information. All pixel data will be transformed into
184 grayscale.
185 $image->get(x, y)
187 Returns the color of the pixel at coordinates (x,y) in the image as
188 a list of three integers between 0 and 255, representing the red,
189 green and blue components respectively.
190 $image->put(data ?,-format=>format-name? ?,-to=> x1 y1 ?x2 y2??)
192 Sets pixels in $image to the data specified in data. This command
193 first searches the list of image file format handlers for a handler
194 that can interpret the data in data, and then reads the image
195 encoded within into $image (the destination image). If data does
196 not match any known format, an attempt to interpret it as a
197 (top-to-bottom) list of scan-lines is made, with each scan-line
198 being a (left-to-right) list of pixel colors (see Tk_GetColor for a
199 description of valid colors.) Every scan-line must be of the same
200 length. Note that when data is a single color name, you are
201 instructing Tk to fill a rectangular region with that color. The
202 following options may be specified:
203 -format =>format-name
205 Specifies the format of the image data in data. Specifically,
206 only image file format handlers whose names begin with format-
207 name will be used while searching for an image data format han‐
208 dler to read the data.
209 -to =>x, y ?, x2, y2?
211 Specifies the coordinates of the top-left corner (x1,y1) of the
212 region of $image into which data from filename are to be read.
213 The default is (0,0). If x2,y2 is given and data is not large
214 enough to cover the rectangle specified by this option, the
215 image data extracted will be tiled so it covers the entire des‐
216 tination rectangle. Note that if data specifies a single color
217 value, then a region extending to the bottom-right corner rep‐
218 resented by (x2,y2) will be filled with that color.
219 $image->read(filename ?,option value(s), ...?)
221 Reads image data from the file named filename into the image. This
222 method first searches the list of image file format handlers for a
223 handler that can interpret the data in filename, and then reads the
224 image in filename into $image (the destination image). The follow‐
225 ing options may be specified:
226 -format => format-name
228 Specifies the format of the image data in filename.
229 Specifically, only image file format handlers whose names
230 begin with format-name will be used while searching for an
231 image data format handler to read the data.
232 -from => x1, y1, x2, y2
234 Specifies a rectangular sub-region of the image file data
235 to be copied to the destination image. If only x1 and y1
236 are specified, the region extends from (x1,y1) to the bot‐
237 tom-right corner of the image in the image file. If all
238 four coordinates are specified, they specify diagonally
239 opposite corners or the region. The default, if this
240 option is not specified, is the whole of the image in the
241 image file.
242 -shrink If this option is specified, the size of $image will be
244 reduced, if necessary, so that the region into which the
245 image file data are read is at the bottom-right corner of
246 the $image. This option will not affect the width or
247 height of the image if the user has specified a non-zero
248 value for the -width or -height configuration option,
249 respectively.
250 -to => x, y
252 Specifies the coordinates of the top-left corner of the
253 region of $image into which data from filename are to be
254 read. The default is (0,0).
255 $image->redither
257 The dithering algorithm used in displaying photo images propagates
258 quantization errors from one pixel to its neighbors. If the image
259 data for $image is supplied in pieces, the dithered image may not
260 be exactly correct. Normally the difference is not noticeable, but
261 if it is a problem, this method can be used to recalculate the
262 dithered image in each window where the image is displayed.
263 $image->transparency(subcommand, ?arg, arg ...?);
265 Allows examination and manipulation of the transparency information
266 in the photo image. Several subcommands are available:
267 $image->transparencyGet(x, y);
269 Returns a boolean indicating if the pixel at (x,y) is transpar‐
270 ent.
271 $image->transparencySet(x, y, boolean);
273 Makes the pixel at (x,y) transparent if boolean is true, and
274 makes that pixel opaque otherwise.
275 $image->write(filename ?,option value(s), ...?)
277 Writes image data from $image to a file named filename. The fol‐
278 lowing options may be specified:
279 -background => color
281 If the color is specified, the data will not contain any
282 transparency information. In all transparent pixels the
283 color will be replaced by the specified color.
284 -format => format-name
286 Specifies the name of the image file format handler to be
287 used to write the data to the file. Specifically, this
288 subcommand searches for the first handler whose name
289 matches a initial substring of format-name and which has
290 the capability to write an image file. If this option is
291 not given, this subcommand uses the first handler that has
292 the capability to write an image file.
293 -from => x1, y1, ?, x2, y2?
295 Specifies a rectangular region of $image to be written to
296 the image file. If only x1 and y1 are specified, the
297 region extends from (x1,y1) to the bottom-right corner of
298 $image. If all four coordinates are given, they specify
299 diagonally opposite corners of the rectangular region. The
300 default, if this option is not given, is the whole image.
301 -grayscale
303 If this options is specified, the data will not contain
304 color information. All pixel data will be transformed into
305 grayscale.
306
308 The photo image code is structured to allow handlers for additional
309 image file formats to be added easily. The photo image code maintains
310 a list of these handlers. Handlers are added to the list by register‐
311 ing them with a call to Tk_CreatePhotoImageFormat. The standard Tk
312 distribution comes with handlers for XBM, XPM, BMP, JPEG, PNG and
313 PPM/PGM formats, which are automatically registered on initialization.
314 When reading an image file or processing string data specified with the
316 -data configuration option, the photo image code invokes each handler
317 in turn until one is found that claims to be able to read the data in
318 the file or string. Usually this will find the correct handler, but if
319 it doesn't, the user may give a format name with the -format option to
320 specify which handler to use. In fact the photo image code will try
321 those handlers whose names begin with the string specified for the
322 -format option (the comparison is case-insensitive). For example, if
323 the user specifies -format => gif, then a handler named GIF87 or GIF89
324 may be invoked, but a handler named JPEG may not (assuming that such
325 handlers had been registered).
326 When writing image data to a file, the processing of the -format option
328 is slightly different: the string value given for the -format option
329 must begin with the complete name of the requested handler, and may
330 contain additional information following that, which the handler can
331 use, for example, to specify which variant to use of the formats sup‐
332 ported by the handler. Note that not all image handlers may support
333 writing transparency data to a file, even where the target image format
334 does.
335
337 When a photo image is displayed in a window, the photo image code allo‐
338 cates colors to use to display the image and dithers the image, if nec‐
339 essary, to display a reasonable approximation to the image using the
340 colors that are available. The colors are allocated as a color cube,
341 that is, the number of colors allocated is the product of the number of
342 shades of red, green and blue.
343 Normally, the number of colors allocated is chosen based on the depth
345 of the window. For example, in an 8-bit PseudoColor window, the photo
346 image code will attempt to allocate seven shades of red, seven shades
347 of green and four shades of blue, for a total of 198 colors. In a
348 1-bit StaticGray (monochrome) window, it will allocate two colors,
349 black and white. In a 24-bit DirectColor or TrueColor window, it will
350 allocate 256 shades each of red, green and blue. Fortunately, because
351 of the way that pixel values can be combined in DirectColor and True‐
352 Color windows, this only requires 256 colors to be allocated. If not
353 all of the colors can be allocated, the photo image code reduces the
354 number of shades of each primary color and tries again.
355 The user can exercise some control over the number of colors that a
357 photo image uses with the -palette configuration option. If this
358 option is used, it specifies the maximum number of shades of each pri‐
359 mary color to try to allocate. It can also be used to force the image
360 to be displayed in shades of gray, even on a color display, by giving a
361 single number rather than three numbers separated by slashes.
362
364 The photo image type was designed and implemented by Paul Mackerras,
365 based on his earlier photo widget and some suggestions from John
366 Ousterhout.
367
369 Tk::Bitmap Tk::Image Tk::Pixmap
370
372 photo, image, color
373perl v5.8.8 2008-02-05 Photo(3)