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
13 transparent. A photo image is stored internally in full color (32 bits
14 per pixel), and is displayed using dithering if necessary. Image data
15 for 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
21 transparencySet subcommand.
22
24 Photos are created using the Photo method. Photo supports the
25 following 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
46 specified gamma exponent value. (The intensity produced by most
47 CRT displays is a power function of the input value, to a good
48 approximation; gamma is the exponent and is typically around 2).
49 The value specified must be greater than zero. The default value
50 is one (no correction). In general, values greater than one will
51 make the image lighter, and values less than one will make it
52 darker.
53 -height => number
55 Specifies the height of the image, in pixels. This option is
56 useful primarily in situations where the user wishes to build up
57 the contents of the image piece by piece. A value of zero (the
58 default) allows the image to expand or shrink vertically to fit the
59 data stored in it.
60 -palette => palette-spec
62 Specifies the resolution of the color cube to be allocated for
63 displaying this image, and thus the number of colors used from the
64 colormaps of the windows where it is displayed. The palette-spec
65 string may be either a single decimal number, specifying the number
66 of shades of gray to use, or three decimal numbers separated by
67 slashes (/), specifying the number of shades of red, green and blue
68 to use, respectively. If the first form (a single number) is used,
69 the image will be displayed in monochrome (i.e., grayscale).
70 -width => number
72 Specifies the width of the image, in pixels. This option is
73 useful primarily in situations where the user wishes to build up
74 the contents of the image piece by piece. A value of zero (the
75 default) allows the image to expand or shrink horizontally to fit
76 the data stored in it.
77
79 When a photo image is created, Tk also creates a new object. This
80 object supports the configure and cget methods described in Tk::options
81 which can be used to enquire and modify the options described above.
82 Those options that write data to the image generally expand the size of
84 the image, if necessary, to accommodate the data written to the image,
85 unless the user has specified non-zero values for the -width and/or
86 -height configuration options, in which case the width and/or height,
87 respectively, of the image will not be changed.
88 The following addition methods are available for photo images:
90 $image->blank
92 Blank the image; that is, set the entire image to have no data, so
93 it will be displayed as transparent, and the background of whatever
94 window it is displayed in will show through.
95 $image->copy(sourceImage ?,option value(s) ...?)
97 Copies a region from the image called $sourceImage (which must be a
98 photo image) to the image called $image, possibly with pixel
99 zooming and/or subsampling. If no options are specified, this
100 method copies the whole of $sourceImage into $image, starting at
101 coordinates (0,0) in $image. The following options may be
102 specified:
103 -from => x1, y1, ? ,x2, y2?
105 Specifies a rectangular sub-region of the source image to
106 be copied. (x1,y1) and (x2,y2) specify diagonally opposite
107 corners of the rectangle. If x2 and y2 are not specified,
108 the default value is the bottom-right corner of the source
109 image. The pixels copied will include the left and top
110 edges of the specified rectangle but not the bottom or
111 right edges. If the -from option is not given, the default
112 is the whole source image.
113 -to => x1, y1, ?, x2, y2?
115 Specifies a rectangular sub-region of the destination image
116 to be affected. (x1,y1) and (x2,y2) specify diagonally
117 opposite corners of the rectangle. If x2 and y2 are not
118 specified, the default value is (x1,y1) plus the size of
119 the source region (after subsampling and zooming, if
120 specified). If x2 and y2 are specified, the source region
121 will be replicated if necessary to fill the destination
122 region in a tiled fashion.
123 -shrink Specifies that the size of the destination image should be
125 reduced, if necessary, so that the region being copied into
126 is at the bottom-right corner of the image. This option
127 will not affect the width or height of the image if the
128 user has specified a non-zero value for the -width or
129 -height configuration option, respectively.
130 -zoom => x, y
132 Specifies that the source region should be magnified by a
133 factor of x in the X direction and y in the Y direction.
134 If y is not given, the default value is the same as x.
135 With this option, each pixel in the source image will be
136 expanded into a block of x x y pixels in the destination
137 image, all the same color. x and y must be greater than 0.
138 -subsample => x, y
140 Specifies that the source image should be reduced in size
141 by using only every xth pixel in the X direction and yth
142 pixel in the Y direction. Negative values will cause the
143 image to be flipped about the Y or X axes, respectively.
144 If y is not given, the default value is the same as x.
145 -compositingrule => rule
147 Specifies how transparent pixels in the source image are
148 combined with the destination image. When a compositing
149 rule of overlay is set, the old contents of the destination
150 image are visible, as if the source image were printed on a
151 piece of transparent film and placed over the top of the
152 destination. When a compositing rule of set is set, the
153 old contents of the destination image are discarded and the
154 source image is used as-is. The default compositing rule
155 is overlay.
156 $image->data(?option value(s), ...?)
158 Returns image data in the form of a string. The following options
159 may be specified:
160 -background => color
162 If the color is specified, the data will not contain any
163 transparency information. In all transparent pixels the
164 color will be replaced by the specified color.
165 -format => format-name
167 Specifies the name of the image file format handler to be
168 used. Specifically, this method searches for the first
169 handler whose name matches a initial substring of format-
170 name and which has the capability to read this image data.
171 If this option is not given, this method uses the first
172 handler that has the capability to read the image data.
173 -from => x1, y1, ?, x2, y2?
175 Specifies a rectangular region of $image to be returned.
176 If only x1 and y1 are specified, the region extends from
177 (x1,y1) to the bottom-right corner of $image. If all four
178 coordinates are given, they specify diagonally opposite
179 corners of the rectangular region, including x1,y1 and
180 excluding x2,y2. The default, if this option is not given,
181 is the whole image.
182 -grayscale
184 If this options is specified, the data will not contain
185 color information. All pixel data will be transformed into
186 grayscale.
187 $image->get(x, y)
189 Returns the color of the pixel at coordinates (x,y) in the image as
190 a list of three integers between 0 and 255, representing the red,
191 green and blue components respectively.
192 $image->put(data ?,-format=>format-name? ?,-to=> x1 y1 ?x2 y2??)
194 Sets pixels in $image to the data specified in data. This command
195 first searches the list of image file format handlers for a handler
196 that can interpret the data in data, and then reads the image
197 encoded within into $image (the destination image). If data does
198 not match any known format, an attempt to interpret it as a (top-
199 to-bottom) list of scan-lines is made, with each scan-line being a
200 (left-to-right) list of pixel colors (see Tk_GetColor for a
201 description of valid colors.) Every scan-line must be of the same
202 length. Note that when data is a single color name, you are
203 instructing Tk to fill a rectangular region with that color. The
204 following options may be specified:
205 -format =>format-name
207 Specifies the format of the image data in data. Specifically,
208 only image file format handlers whose names begin with format-
209 name will be used while searching for an image data format
210 handler to read the data.
211 -to =>x, y ?, x2, y2?
213 Specifies the coordinates of the top-left corner (x1,y1) of the
214 region of $image into which data from filename are to be read.
215 The default is (0,0). If x2,y2 is given and data is not large
216 enough to cover the rectangle specified by this option, the
217 image data extracted will be tiled so it covers the entire
218 destination rectangle. Note that if data specifies a single
219 color value, then a region extending to the bottom-right corner
220 represented by (x2,y2) will be filled with that color.
221 $image->read(filename ?,option value(s), ...?)
223 Reads image data from the file named filename into the image. This
224 method first searches the list of image file format handlers for a
225 handler that can interpret the data in filename, and then reads the
226 image in filename into $image (the destination image). The
227 following options may be specified:
228 -format => format-name
230 Specifies the format of the image data in filename.
231 Specifically, only image file format handlers whose names
232 begin with format-name will be used while searching for an
233 image data format handler to read the data.
234 -from => x1, y1, x2, y2
236 Specifies a rectangular sub-region of the image file data
237 to be copied to the destination image. If only x1 and y1
238 are specified, the region extends from (x1,y1) to the
239 bottom-right corner of the image in the image file. If all
240 four coordinates are specified, they specify diagonally
241 opposite corners or the region. The default, if this
242 option is not specified, is the whole of the image in the
243 image file.
244 -shrink If this option is specified, the size of $image will be
246 reduced, if necessary, so that the region into which the
247 image file data are read is at the bottom-right corner of
248 the $image. This option will not affect the width or
249 height of the image if the user has specified a non-zero
250 value for the -width or -height configuration option,
251 respectively.
252 -to => x, y
254 Specifies the coordinates of the top-left corner of the
255 region of $image into which data from filename are to be
256 read. The default is (0,0).
257 $image->redither
259 The dithering algorithm used in displaying photo images propagates
260 quantization errors from one pixel to its neighbors. If the image
261 data for $image is supplied in pieces, the dithered image may not
262 be exactly correct. Normally the difference is not noticeable, but
263 if it is a problem, this method can be used to recalculate the
264 dithered image in each window where the image is displayed.
265 $image->transparency(subcommand, ?arg, arg ...?);
267 Allows examination and manipulation of the transparency information
268 in the photo image. Several subcommands are available:
269 $image->transparencyGet(x, y);
271 Returns a boolean indicating if the pixel at (x,y) is
272 transparent.
273 $image->transparencySet(x, y, boolean);
275 Makes the pixel at (x,y) transparent if boolean is true, and
276 makes that pixel opaque otherwise.
277 $image->write(filename ?,option value(s), ...?)
279 Writes image data from $image to a file named filename. The
280 following options may be specified:
281 -background => color
283 If the color is specified, the data will not contain any
284 transparency information. In all transparent pixels the
285 color will be replaced by the specified color.
286 -format => format-name
288 Specifies the name of the image file format handler to be
289 used to write the data to the file. Specifically, this
290 subcommand searches for the first handler whose name
291 matches a initial substring of format-name and which has
292 the capability to write an image file. If this option is
293 not given, this subcommand uses the first handler that has
294 the capability to write an image file.
295 -from => x1, y1, ?, x2, y2?
297 Specifies a rectangular region of $image to be written to
298 the image file. If only x1 and y1 are specified, the
299 region extends from (x1,y1) to the bottom-right corner of
300 $image. If all four coordinates are given, they specify
301 diagonally opposite corners of the rectangular region. The
302 default, if this option is not given, is the whole image.
303 -grayscale
305 If this options is specified, the data will not contain
306 color information. All pixel data will be transformed into
307 grayscale.
308
310 The photo image code is structured to allow handlers for additional
311 image file formats to be added easily. The photo image code maintains
312 a list of these handlers. Handlers are added to the list by
313 registering them with a call to Tk_CreatePhotoImageFormat. The
314 standard Tk distribution comes with handlers for XBM, XPM, BMP, JPEG,
315 PNG and PPM/PGM formats, which are automatically registered on
316 initialization.
317 When reading an image file or processing string data specified with the
319 -data configuration option, the photo image code invokes each handler
320 in turn until one is found that claims to be able to read the data in
321 the file or string. Usually this will find the correct handler, but if
322 it doesn't, the user may give a format name with the -format option to
323 specify which handler to use. In fact the photo image code will try
324 those handlers whose names begin with the string specified for the
325 -format option (the comparison is case-insensitive). For example, if
326 the user specifies -format => gif, then a handler named GIF87 or GIF89
327 may be invoked, but a handler named JPEG may not (assuming that such
328 handlers had been registered).
329 When writing image data to a file, the processing of the -format option
331 is slightly different: the string value given for the -format option
332 must begin with the complete name of the requested handler, and may
333 contain additional information following that, which the handler can
334 use, for example, to specify which variant to use of the formats
335 supported by the handler. Note that not all image handlers may support
336 writing transparency data to a file, even where the target image format
337 does.
338
340 When a photo image is displayed in a window, the photo image code
341 allocates colors to use to display the image and dithers the image, if
342 necessary, to display a reasonable approximation to the image using the
343 colors that are available. The colors are allocated as a color cube,
344 that is, the number of colors allocated is the product of the number of
345 shades of red, green and blue.
346 Normally, the number of colors allocated is chosen based on the depth
348 of the window. For example, in an 8-bit PseudoColor window, the photo
349 image code will attempt to allocate seven shades of red, seven shades
350 of green and four shades of blue, for a total of 198 colors. In a
351 1-bit StaticGray (monochrome) window, it will allocate two colors,
352 black and white. In a 24-bit DirectColor or TrueColor window, it will
353 allocate 256 shades each of red, green and blue. Fortunately, because
354 of the way that pixel values can be combined in DirectColor and
355 TrueColor windows, this only requires 256 colors to be allocated. If
356 not all of the colors can be allocated, the photo image code reduces
357 the number of shades of each primary color and tries again.
358 The user can exercise some control over the number of colors that a
360 photo image uses with the -palette configuration option. If this
361 option is used, it specifies the maximum number of shades of each
362 primary color to try to allocate. It can also be used to force the
363 image to be displayed in shades of gray, even on a color display, by
364 giving a single number rather than three numbers separated by slashes.
365
367 The photo image type was designed and implemented by Paul Mackerras,
368 based on his earlier photo widget and some suggestions from John
369 Ousterhout.
370
372 Tk::Bitmap Tk::Image Tk::Pixmap
373
375 photo, image, color
376perl v5.36.0 2023-01-20 Photo(3)