Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | # Copyright (c) 1994 The Australian National University |
2 | # Copyright (c) 1994-1997 Sun Microsystems, Inc. | |
3 | # See the file "license.terms" for information on usage and redistribution | |
4 | # of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
5 | # Author: Paul Mackerras (paulus@cs.anu.edu.au), | |
6 | # Department of Computer Science, | |
7 | # Australian National University. | |
8 | # RCS: @(#) $Id: photo.n,v 1.2 1998/09/14 18:22:59 stanton Exp $ | |
9 | # | |
10 | ||
11 | =head1 NAME | |
12 | ||
13 | Tk::Photo - Full-color images | |
14 | ||
15 | =for category Tk Image Classes | |
16 | ||
17 | =head1 SYNOPSIS | |
18 | ||
19 | S< >I<$widget>-E<gt>B<Photo>(?I<name>??, I<options>?) | |
20 | ||
21 | =head1 DESCRIPTION | |
22 | ||
23 | A photo is an L<image|Tk::Image> whose pixels can display any color or be | |
24 | transparent. A photo image is stored internally in full color (32 | |
25 | bits per pixel), and is displayed using dithering if necessary. Image | |
26 | data for a photo image can be obtained from a file or a string, or it | |
27 | can be supplied from | |
28 | C code through a procedural interface. At present, only GIF and PPM/PGM | |
29 | formats are supported, but an interface exists to allow additional | |
30 | image file formats to be added easily. A photo image is transparent | |
31 | in regions where no image data has been supplied. | |
32 | ||
33 | =head1 CREATING PHOTOS | |
34 | ||
35 | Photos are created using the B<Photo> method. | |
36 | B<Photo> supports the following I<options>: | |
37 | ||
38 | =over 4 | |
39 | ||
40 | =item B<-data> =E<gt> I<string> | |
41 | ||
42 | Specifies the contents of the image as a string. The format of the | |
43 | string must be one of those for which there is an image file format | |
44 | handler that will accept string data. If both the B<-data> | |
45 | and B<-file> options are specified, the B<-file> option takes | |
46 | precedence. | |
47 | ||
48 | =item B<-format> =E<gt> I<format-name> | |
49 | ||
50 | Specifies the name of the file format for the data specified with the | |
51 | B<-data> or B<-file> option. | |
52 | ||
53 | =item B<-file> =E<gt> I<name> | |
54 | ||
55 | I<name> gives the name of a file that is to be read to supply data | |
56 | for the photo image. The file format must be one of those for which | |
57 | there is an image file format handler that can read data. | |
58 | ||
59 | =item B<-gamma> =E<gt> I<value> | |
60 | ||
61 | Specifies that the colors allocated for displaying this image in a | |
62 | window should be corrected for a non-linear display with the specified | |
63 | gamma exponent value. (The intensity produced by most | |
64 | CRT displays is a power function of the input value, to a good | |
65 | approximation; gamma is the exponent and is typically around 2). | |
66 | The value specified must be greater than zero. The default | |
67 | value is one (no correction). In general, values greater than one | |
68 | will make the image lighter, and values less than one will make it | |
69 | darker. | |
70 | ||
71 | =item B<-height> =E<gt> I<number> | |
72 | ||
73 | Specifies the height of the image, in pixels. This option is useful | |
74 | primarily in situations where the user wishes to build up the contents | |
75 | of the image piece by piece. A value of zero (the default) allows the | |
76 | image to expand or shrink vertically to fit the data stored in it. | |
77 | ||
78 | =item B<-palette> =E<gt> I<palette-spec> | |
79 | ||
80 | Specifies the resolution of the color cube to be allocated for | |
81 | displaying this image, and thus the number of colors used from the | |
82 | colormaps of the windows where it is displayed. The | |
83 | I<palette-spec> string may be either a single decimal number, | |
84 | specifying the number of shades of gray to use, or three decimal | |
85 | numbers separated by slashes (/), specifying the number of shades of | |
86 | red, green and blue to use, respectively. If the first form (a single | |
87 | number) is used, the image will be displayed in monochrome (i.e., | |
88 | grayscale). | |
89 | ||
90 | =item B<-width> =E<gt> I<number> | |
91 | ||
92 | Specifies the width of the image, in pixels. This option is useful | |
93 | primarily in situations where the user wishes to build up the contents | |
94 | of the image piece by piece. A value of zero (the default) allows the | |
95 | image to expand or shrink horizontally to fit the data stored in it. | |
96 | ||
97 | =back | |
98 | ||
99 | =head1 IMAGE METHODS | |
100 | ||
101 | When a photo image is created, Tk also creates a new object. | |
102 | This object supports the B<configure> and B<cget> methods | |
103 | described in L<Tk::options> which can be used to enquire and | |
104 | modify the options described above. | |
105 | ||
106 | Those options that write data to the image generally expand the size | |
107 | of the image, if necessary, to accommodate the data written to the | |
108 | image, unless the user has specified non-zero values for the | |
109 | B<-width> and/or B<-height> configuration options, in which | |
110 | case the width and/or height, respectively, of the image will not be | |
111 | changed. | |
112 | ||
113 | The following addition methods are available for photo images: | |
114 | ||
115 | =over 4 | |
116 | ||
117 | =item I<$image>-E<gt>B<blank> | |
118 | ||
119 | Blank the image; that is, set the entire image to have no data, so it | |
120 | will be displayed as transparent, and the background of whatever | |
121 | window it is displayed in will show through. | |
122 | ||
123 | =item I<$image>-E<gt>B<copy>(I<sourceImage> ?,I<option value(s) ...>?) | |
124 | ||
125 | Copies a region from the image called I<sourceImage> (which must | |
126 | be a photo image) to the image called I<$image>, possibly with | |
127 | pixel zooming and/or subsampling. If no options are specified, this | |
128 | method copies the whole of I<sourceImage> into I<$image>, | |
129 | starting at coordinates (0,0) in I<$image>. The following | |
130 | options may be specified: | |
131 | ||
132 | =over 8 | |
133 | ||
134 | =item B<-from> =E<gt> I<x1 y1 ?x2 y2?> | |
135 | ||
136 | Specifies a rectangular sub-region of the source image to be copied. | |
137 | (I<x1,y1>) and (I<x2,y2>) specify diagonally opposite corners of | |
138 | the rectangle. If I<x2> and I<y2> are not specified, the | |
139 | default value is the bottom-right corner of the source image. The | |
140 | pixels copied will include the left and top edges of the specified | |
141 | rectangle but not the bottom or right edges. If the B<-from> | |
142 | option is not given, the default is the whole source image. | |
143 | ||
144 | =item B<-to> =E<gt> I<x1 y1 ?x2 y2?> | |
145 | ||
146 | Specifies a rectangular sub-region of the destination image to be | |
147 | affected. (I<x1,y1>) and (I<x2,y2>) specify diagonally opposite | |
148 | corners of the rectangle. If I<x2> and I<y2> are not specified, | |
149 | the default value is (I<x1,y1>) plus the size of the source | |
150 | region (after subsampling and zooming, if specified). If I<x2> and | |
151 | I<y2> are specified, the source region will be replicated if | |
152 | necessary to fill the destination region in a tiled fashion. | |
153 | ||
154 | =item B<-shrink> | |
155 | ||
156 | Specifies that the size of the destination image should be reduced, if | |
157 | necessary, so that the region being copied into is at the bottom-right | |
158 | corner of the image. This option will not affect the width or height | |
159 | of the image if the user has specified a non-zero value for the | |
160 | B<-width> or B<-height> configuration option, respectively. | |
161 | ||
162 | =item B<-zoom> =E<gt> I<x y> | |
163 | ||
164 | Specifies that the source region should be magnified by a factor of | |
165 | I<x> in the X direction and I<y> in the Y direction. If I<y> | |
166 | is not given, the default value is the same as I<x>. With this | |
167 | option, each pixel in the source image will be expanded into a block | |
168 | of I<x> x I<y> pixels in the destination image, all the same | |
169 | color. I<x> and I<y> must be greater than 0. | |
170 | ||
171 | =item B<-subsample> =E<gt> I<x y> | |
172 | ||
173 | Specifies that the source image should be reduced in size by using | |
174 | only every I<x>th pixel in the X direction and I<y>th pixel in | |
175 | the Y direction. Negative values will cause the image to be flipped | |
176 | about the Y or X axes, respectively. If I<y> is not given, the | |
177 | default value is the same as I<x>. | |
178 | ||
179 | =back | |
180 | ||
181 | =item I<$image>-E<gt>B<data>(?I<option value(s), ...>?) | |
182 | ||
183 | returns image data in the form of a string. | |
184 | The following options may be specified: | |
185 | ||
186 | =over 8 | |
187 | ||
188 | =item B<-background> =E<gt> I< color> | |
189 | ||
190 | If the color is specified, the data will not contain any transparency | |
191 | information. In all transparent pixels the color will be replaced by | |
192 | the specified color. | |
193 | ||
194 | =item B<-format> =E<gt> I<format-name> | |
195 | ||
196 | Specifies the name of the image file format handler to be used to | |
197 | convert the data. Specifically, this method searches | |
198 | for the first handler whose name matches a initial substring of | |
199 | I<format-name> and which has the capability to write an string. | |
200 | If this option is not given, the data is returned in the default | |
201 | format as accepted by I<$image>-E<gt>B<put>. | |
202 | ||
203 | =item B<-from> =E<gt> I<x1 y1 ?x2 y2?> | |
204 | ||
205 | Specifies a rectangular region of I<$image> to be written to the | |
206 | string. If only I<x1> and I<y1> are specified, the region | |
207 | extends from I<(x1,y1)> to the bottom-right corner of | |
208 | I<$image>. If all four coordinates are given, they specify | |
209 | diagonally opposite corners of the rectangular region. The default, | |
210 | if this option is not given, is the whole image. | |
211 | ||
212 | =back | |
213 | ||
214 | =item B<-grayscale> | |
215 | ||
216 | If this options is specified, the data will not contain color | |
217 | information. All pixel data will be transformed into grayscale. | |
218 | ||
219 | =item I<$image>-E<gt>B<get>(I<x,y>) | |
220 | ||
221 | Returns the color of the pixel at coordinates (I<x>,I<y>) in the | |
222 | image as a list of three integers between 0 and 255, representing the | |
223 | red, green and blue components respectively. | |
224 | ||
225 | =item I<$image>-E<gt>B<put>(I<data> ?,B<-format>=E<gt>I<format-name>? ?,B<-to>=E<gt>I< x1 y1 ?x2 y2?>?) | |
226 | ||
227 | Sets pixels in I< imageName> to the data specified in | |
228 | I<data>. This command first searches the list of image file | |
229 | format handlers for a handler that can interpret the data | |
230 | in I<data>, and then reads the image in I<filename> into | |
231 | I<imageName> (the destination image). The following options | |
232 | may be specified: | |
233 | ||
234 | =over 4 | |
235 | ||
236 | =item B<-format >I<format-name> | |
237 | ||
238 | Specifies the format of the image data in I<data>. | |
239 | Specifically, only image file format handlers whose names begin with | |
240 | I<format-name> will be used while searching for an image data | |
241 | format handler to read the data. Otherwise I<data> is used to form a two-dimensional array of pixels | |
242 | that are then copied into the I<$image>. I<data> is structured | |
243 | then as a list of horizontal rows, from top to bottom, each of which is | |
244 | a list of colors, listed from left to right. Each color may be specified | |
245 | by name (e.g., blue) or in hexadecimal form (e.g., #2376af). | |
246 | ||
247 | =item B<-from >I<x1 y1 x2 y2> | |
248 | ||
249 | Specifies a rectangular sub-region of the image file data to be | |
250 | returned. If only I<x1> and I<y1> are specified, the region | |
251 | extends from (I<x1,y1>) to the bottom-right corner of the image | |
252 | in the image file. If all four coordinates are specified, they | |
253 | specify diagonally opposite corners or the region. The default, | |
254 | if this option is not specified, is the whole of the image. | |
255 | ||
256 | =item B<-shrink> | |
257 | ||
258 | If this option, the size of I<imageName> will be reduced, if | |
259 | necessary, so that the region into which the image file data are read | |
260 | is at the bottom-right corner of the I<imageName>. This option | |
261 | will not affect the width or height of the image if the user has | |
262 | specified a non-zero value for the B<-width> or B<-height> | |
263 | configuration option, respectively. | |
264 | ||
265 | =item B<-to >I<x y> | |
266 | ||
267 | Specifies the coordinates of the top-left corner of the region of | |
268 | I<imageName> into which data from I<filename> are to be read. | |
269 | The default is (0,0). | |
270 | ||
271 | =back | |
272 | ||
273 | =item I<$image>-E<gt>B<read>(I<filename> ?,I<option value(s), ...>?) | |
274 | ||
275 | Reads image data from the file named I<filename> into the image. | |
276 | This method first searches the list of | |
277 | image file format handlers for a handler that can interpret the data | |
278 | in I<filename>, and then reads the image in I<filename> into | |
279 | I<$image> (the destination image). The following options may be | |
280 | specified: | |
281 | ||
282 | =over 8 | |
283 | ||
284 | =item B<-format> =E<gt> I<format-name> | |
285 | ||
286 | Specifies the format of the image data in I<filename>. | |
287 | Specifically, only image file format handlers whose names begin with | |
288 | I<format-name> will be used while searching for an image data | |
289 | format handler to read the data. | |
290 | ||
291 | =item B<-from> =E<gt> I<x1 y1 ?x2 y2?> | |
292 | ||
293 | Specifies a rectangular sub-region of the image file data to be copied | |
294 | to the destination image. If only I<x1> and I<y1> are | |
295 | specified, the region extends from (I<x1,y1>) to the bottom-right | |
296 | corner of the image in the image file. If all four coordinates are | |
297 | specified, they specify diagonally opposite corners or the region. | |
298 | The default, if this option is not specified, is the whole of the | |
299 | image in the image file. | |
300 | ||
301 | =item B<-shrink> | |
302 | ||
303 | If this option, the size of I<$image> will be reduced, if | |
304 | necessary, so that the region into which the image file data are read | |
305 | is at the bottom-right corner of the I<$image>. This option | |
306 | will not affect the width or height of the image if the user has | |
307 | specified a non-zero value for the B<-width> or B<-height> | |
308 | configuration option, respectively. | |
309 | ||
310 | =item B<-to> =E<gt> I<x y> | |
311 | ||
312 | Specifies the coordinates of the top-left corner of the region of | |
313 | I<$image> into which data from I<filename> are to be read. | |
314 | The default is (0,0). | |
315 | ||
316 | =back | |
317 | ||
318 | =item I<$image>-E<gt>B<redither> | |
319 | ||
320 | The dithering algorithm used in displaying photo images propagates | |
321 | quantization errors from one pixel to its neighbors. | |
322 | If the image data for I<$image> is supplied in pieces, the | |
323 | dithered image may not be exactly correct. Normally the difference is | |
324 | not noticeable, but if it is a problem, this method can be used to | |
325 | recalculate the dithered image in each window where the image is | |
326 | displayed. | |
327 | ||
328 | =item I<$image>-E<gt>B<write>(I<filename> ?,I<option value(s), ...>?) | |
329 | ||
330 | Writes image data from I<$image> to a file named I<filename>. | |
331 | The following options may be specified: | |
332 | ||
333 | =over 8 | |
334 | ||
335 | =item B<-background>I< color> | |
336 | ||
337 | If the color is specified, the data will not contain any transparency | |
338 | information. In all transparent pixels the color will be replaced by | |
339 | the specified color. | |
340 | ||
341 | =item B<-format> =E<gt> I<format-name> | |
342 | ||
343 | Specifies the name of the image file format handler to be used to | |
344 | write the data to the file. Specifically, this subcommand searches | |
345 | for the first handler whose name matches a initial substring of | |
346 | I<format-name> and which has the capability to write an image | |
347 | file. If this option is not given, this subcommand uses the first | |
348 | handler that has the capability to write an image file. | |
349 | ||
350 | =item B<-from> =E<gt> I<x1 y1 ?x2 y2?> | |
351 | ||
352 | Specifies a rectangular region of I<$image> to be written to the | |
353 | image file. If only I<x1> and I<y1> are specified, the region | |
354 | extends from I<(x1,y1)> to the bottom-right corner of | |
355 | I<$image>. If all four coordinates are given, they specify | |
356 | diagonally opposite corners of the rectangular region. The default, | |
357 | if this option is not given, is the whole image. | |
358 | ||
359 | ||
360 | =item B<-grayscale> | |
361 | ||
362 | If this options is specified, the data will not contain color | |
363 | information. All pixel data will be transformed into grayscale. | |
364 | ||
365 | =back | |
366 | ||
367 | =back | |
368 | ||
369 | =head1 IMAGE FORMATS | |
370 | ||
371 | The photo image code is structured to allow handlers for additional | |
372 | image file formats to be added easily. The photo image code maintains | |
373 | a list of these handlers. Handlers are added to the list by | |
374 | registering them with a call to B<Tk_CreatePhotoImageFormat>. The | |
375 | standard Tk distribution comes with handlers for PPM/PGM and GIF formats, | |
376 | which are automatically registered on initialization. | |
377 | ||
378 | When reading an image file or processing | |
379 | string data specified with the B<-data> configuration option, the | |
380 | photo image code invokes each handler in turn until one is | |
381 | found that claims to be able to read the data in the file or string. | |
382 | Usually this will find the correct handler, but if it doesn't, the | |
383 | user may give a format name with the B<-format> option to specify | |
384 | which handler to use. In fact the photo image code will try those | |
385 | handlers whose names begin with the string specified for the | |
386 | B<-format> option (the comparison is case-insensitive). For | |
387 | example, if the user specifies B<-format gif>, then a handler | |
388 | named GIF87 or GIF89 may be invoked, but a handler | |
389 | named JPEG may not (assuming that such handlers had been | |
390 | registered). | |
391 | ||
392 | When writing image data to a file, the processing of the | |
393 | B<-format> option is slightly different: the string value given | |
394 | for the B<-format> option must begin with the complete name of the | |
395 | requested handler, and may contain additional information following | |
396 | that, which the handler can use, for example, to specify which variant | |
397 | to use of the formats supported by the handler. | |
398 | ||
399 | =head1 COLOR ALLOCATION | |
400 | ||
401 | When a photo image is displayed in a window, the photo image code | |
402 | allocates colors to use to display the image and dithers the image, if | |
403 | necessary, to display a reasonable approximation to the image using | |
404 | the colors that are available. The colors are allocated as a color | |
405 | cube, that is, the number of colors allocated is the product of the | |
406 | number of shades of red, green and blue. | |
407 | ||
408 | Normally, the number of | |
409 | colors allocated is chosen based on the depth of the window. For | |
410 | example, in an 8-bit PseudoColor window, the photo image code will | |
411 | attempt to allocate seven shades of red, seven shades of green and | |
412 | four shades of blue, for a total of 198 colors. In a 1-bit StaticGray | |
413 | (monochrome) window, it will allocate two colors, black and white. In | |
414 | a 24-bit DirectColor or TrueColor window, it will allocate 256 shades | |
415 | each of red, green and blue. Fortunately, because of the way that | |
416 | pixel values can be combined in DirectColor and TrueColor windows, | |
417 | this only requires 256 colors to be allocated. If not all of the | |
418 | colors can be allocated, the photo image code reduces the number of | |
419 | shades of each primary color and tries again. | |
420 | ||
421 | The user can exercise some control over the number of colors that a | |
422 | photo image uses with the B<-palette> configuration option. If | |
423 | this option is used, it specifies the maximum number of shades of | |
424 | each primary color to try to allocate. It can also be used to force | |
425 | the image to be displayed in shades of gray, even on a color display, | |
426 | by giving a single number rather than three numbers separated by | |
427 | slashes. | |
428 | ||
429 | =head1 CREDITS | |
430 | ||
431 | The photo image type was designed and implemented by Paul Mackerras, | |
432 | based on his earlier photo widget and some suggestions from | |
433 | John Ousterhout. | |
434 | ||
435 | =head1 SEE ALSO | |
436 | ||
437 | L<Tk::Bitmap|Tk::Bitmap> | |
438 | L<Tk::Image|Tk::Image> | |
439 | L<Tk::Pixmap|Tk::Pixmap> | |
440 | ||
441 | =head1 KEYWORDS | |
442 | ||
443 | photo, image, color | |
444 | ||
445 | =cut | |
446 | ||
447 |