1Photo(3)              User Contributed Perl Documentation             Photo(3)
2
3
4

NAME

6       Tk::Photo - Full-color images
7

SYNOPSIS

9           $widget->Photo(?name??, options?)
10

DESCRIPTION

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

CREATING PHOTOS

24       Photos are created using the Photo method.  Photo supports the
25       following options:
26
27       -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
34       -format => format-name
35           Specifies the name of the file format for the data specified with
36           the -data or -file option.
37
38       -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
43       -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
54       -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
61       -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
71       -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

IMAGE METHODS

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
83       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
89       The following addition methods are available for photo images:
90
91       $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
96       $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
104           -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
114           -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
124           -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
131           -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
139           -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
146           -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
157       $image->data(?option value(s), ...?)
158           Returns image data in the form of a string.  The following options
159           may be specified:
160
161           -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
166           -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
174           -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
183           -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
188       $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
193       $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
206           -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
212           -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
222       $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
229           -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
235           -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
245           -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
253           -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
258       $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
266       $image->transparency(subcommand, ?arg, arg ...?);
267           Allows examination and manipulation of the transparency information
268           in the photo image.  Several subcommands are available:
269
270           $image->transparencyGet(x, y);
271               Returns a boolean indicating if the pixel at (x,y) is
272               transparent.
273
274           $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
278       $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
282           -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
287           -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
296           -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
304           -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

IMAGE FORMATS

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
318       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
330       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

COLOR ALLOCATION

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
347       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
359       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

CREDITS

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

SEE ALSO

372       Tk::Bitmap Tk::Image Tk::Pixmap
373

KEYWORDS

375       photo, image, color
376
377
378
379perl v5.38.0                      2023-07-21                          Photo(3)
Impressum