diff options
Diffstat (limited to 'doc/photo.n')
| -rw-r--r-- | doc/photo.n | 344 |
1 files changed, 344 insertions, 0 deletions
diff --git a/doc/photo.n b/doc/photo.n new file mode 100644 index 0000000..1e26f8a --- /dev/null +++ b/doc/photo.n @@ -0,0 +1,344 @@ +'\" +'\" Copyright (c) 1994 The Australian National University +'\" Copyright (c) 1994-1997 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" Author: Paul Mackerras (paulus@cs.anu.edu.au), +'\" Department of Computer Science, +'\" Australian National University. +'\" +'\" "@(#) photo.n 1.12 97/10/14 10:52:30" +'\" +.so man.macros +.TH photo n 4.0 Tk "Tk Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +photo \- Full-color images +.SH SYNOPSIS +\fBimage create photo \fR?\fIname\fR? ?\fIoptions\fR? +.BE + +.SH DESCRIPTION +.PP +A photo is an image whose pixels can display any color or be +transparent. A photo image is stored internally in full color (24 +bits per pixel), and is displayed using dithering if necessary. Image +data for a photo image can be obtained from a file or a string, or it +can be supplied from +C code through a procedural interface. At present, only GIF and PPM/PGM +formats are supported, but an interface exists to allow additional +image file formats to be added easily. A photo image is transparent +in regions where no image data has been supplied. + +.SH "CREATING PHOTOS" +.PP +Like all images, photos are created using the \fBimage create\fR +command. +Photos support the following \fIoptions\fR: +.TP +\fB\-data \fIstring\fR +Specifies the contents of the image as a string. The format of the +string must be one of those for which there is an image file format +handler that will accept string data. If both the \fB\-data\fR +and \fB\-file\fR options are specified, the \fB\-file\fR option takes +precedence. +.TP +\fB\-format \fIformat-name\fR +Specifies the name of the file format for the data specified with the +\fB\-data\fR or \fB\-file\fR option. +.TP +\fB\-file \fIname\fR +\fIname\fR gives the name of a file that is to be read to supply data +for the photo image. The file format must be one of those for which +there is an image file format handler that can read data. +.TP +\fB\-gamma \fIvalue\fR +Specifies that the colors allocated for displaying this image in a +window should be corrected for a non-linear display with the specified +gamma exponent value. (The intensity produced by most +CRT displays is a power function of the input value, to a good +approximation; gamma is the exponent and is typically around 2). +The value specified must be greater than zero. The default +value is one (no correction). In general, values greater than one +will make the image lighter, and values less than one will make it +darker. +.TP +\fB\-height \fInumber\fR +Specifies the height of the image, in pixels. This option is useful +primarily in situations where the user wishes to build up the contents +of the image piece by piece. A value of zero (the default) allows the +image to expand or shrink vertically to fit the data stored in it. +.TP +\fB\-palette \fIpalette-spec\fR +Specifies the resolution of the color cube to be allocated for +displaying this image, and thus the number of colors used from the +colormaps of the windows where it is displayed. The +\fIpalette-spec\fR string may be either a single decimal number, +specifying the number of shades of gray to use, or three decimal +numbers separated by slashes (/), specifying the number of shades of +red, green and blue to use, respectively. If the first form (a single +number) is used, the image will be displayed in monochrome (i.e., +grayscale). +.TP +\fB\-width \fInumber\fR +Specifies the width of the image, in pixels. This option is useful +primarily in situations where the user wishes to build up the contents +of the image piece by piece. A value of zero (the default) allows the +image to expand or shrink horizontally to fit the data stored in it. + +.SH "IMAGE COMMAND" +.PP +When a photo image is created, Tk also creates a new command +whose name is the same as the image. +This command may be used to invoke various operations +on the image. +It has the following general form: +.CS +\fIimageName option \fR?\fIarg arg ...\fR? +.CE +\fIOption\fR and the \fIarg\fRs +determine the exact behavior of the command. +.PP +Those options that write data to the image generally expand the size +of the image, if necessary, to accommodate the data written to the +image, unless the user has specified non-zero values for the +\fB\-width\fR and/or \fB\-height\fR configuration options, in which +case the width and/or height, respectively, of the image will not be +changed. +.PP +The following commands are possible for photo images: +.TP +\fIimageName \fBblank\fR +Blank the image; that is, set the entire image to have no data, so it +will be displayed as transparent, and the background of whatever +window it is displayed in will show through. +.TP +\fIimageName \fBcget\fR \fIoption\fR +Returns the current value of the configuration option given +by \fIoption\fR. +\fIOption\fR may have any of the values accepted by the +\fBimage create photo\fR command. +.TP +\fIimageName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR? +Query or modify the configuration options for the image. +If no \fIoption\fR is specified, returns a list describing all of +the available options for \fIimageName\fR (see \fBTk_ConfigureInfo\fR for +information on the format of this list). If \fIoption\fR is specified +with no \fIvalue\fR, then the command returns a list describing the +one named option (this list will be identical to the corresponding +sublist of the value returned if no \fIoption\fR is specified). If +one or more \fIoption\-value\fR pairs are specified, then the command +modifies the given option(s) to have the given value(s); in +this case the command returns an empty string. +\fIOption\fR may have any of the values accepted by the +\fBimage create photo\fR command. +.TP +\fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? +Copies a region from the image called \fIsourceImage\fR (which must +be a photo image) to the image called \fIimageName\fR, possibly with +pixel zooming and/or subsampling. If no options are specified, this +command copies the whole of \fIsourceImage\fR into \fIimageName\fR, +starting at coordinates (0,0) in \fIimageName\fR. The following +options may be specified: +.RS +.TP +\fB\-from \fIx1 y1 x2 y2\fR +Specifies a rectangular sub-region of the source image to be copied. +(\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite corners of +the rectangle. If \fIx2\fR and \fIy2\fR are not specified, the +default value is the bottom-right corner of the source image. The +pixels copied will include the left and top edges of the specified +rectangle but not the bottom or right edges. If the \fB\-from\fR +option is not given, the default is the whole source image. +.TP +\fB\-to \fIx1 y1 x2 y2\fR +Specifies a rectangular sub-region of the destination image to be +affected. (\fIx1,y1\fR) and (\fIx2,y2\fR) specify diagonally opposite +corners of the rectangle. If \fIx2\fR and \fIy2\fR are not specified, +the default value is (\fIx1,y1\fR) plus the size of the source +region (after subsampling and zooming, if specified). If \fIx2\fR and +\fIy2\fR are specified, the source region will be replicated if +necessary to fill the destination region in a tiled fashion. +.TP +\fB\-shrink\fR +Specifies that the size of the destination image should be reduced, if +necessary, so that the region being copied into is at the bottom-right +corner of the image. This option will not affect the width or height +of the image if the user has specified a non-zero value for the +\fB\-width\fR or \fB\-height\fR configuration option, respectively. +.TP +\fB\-zoom \fIx y\fR +Specifies that the source region should be magnified by a factor of +\fIx\fR in the X direction and \fIy\fR in the Y direction. If \fIy\fR +is not given, the default value is the same as \fIx\fR. With this +option, each pixel in the source image will be expanded into a block +of \fIx\fR x \fIy\fR pixels in the destination image, all the same +color. \fIx\fR and \fIy\fR must be greater than 0. +.TP +\fB\-subsample \fIx y\fR +Specifies that the source image should be reduced in size by using +only every \fIx\fRth pixel in the X direction and \fIy\fRth pixel in +the Y direction. Negative values will cause the image to be flipped +about the Y or X axes, respectively. If \fIy\fR is not given, the +default value is the same as \fIx\fR. +.RE +.TP +\fIimageName \fBget\fR \fIx y\fR +Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the +image as a list of three integers between 0 and 255, representing the +red, green and blue components respectively. +.TP +\fIimageName \fBput \fIdata\fR ?\fB\-to\fI x1 y1 x2 y2\fR? +Sets pixels in \fIimageName\fR to the colors specified in \fIdata\fR. +\fIdata\fR is used to form a two-dimensional array of pixels that are +then copied into the \fIimageName\fR. \fIdata\fR is structured as a +list of horizontal rows, from top to bottom, each of which is a list +of colors, listed from left to right. Each color may be specified by name +(e.g., blue) or in hexadecimal form (e.g., #2376af). The +\fB\-to\fR option can be used to specify the area of \fIimageName\fR to be +affected. If only \fIx1\fR and \fIy1\fR are given, the area affected +has its top-left corner at (\fIx1,y1\fR) and is the same size as the +array given in \fIdata\fR. If all four coordinates are given, they +specify diagonally opposite corners of the affected rectangle, and the +array given in \fIdata\fR will be replicated as necessary in the X and +Y directions to fill the rectangle. +.TP +\fIimageName \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR? +Reads image data from the file named \fIfilename\fR into the image. +This command first searches the list of +image file format handlers for a handler that can interpret the data +in \fIfilename\fR, and then reads the image in \fIfilename\fR into +\fIimageName\fR (the destination image). The following options may be +specified: +.RS +.TP +\fB\-format \fIformat-name\fR +Specifies the format of the image data in \fIfilename\fR. +Specifically, only image file format handlers whose names begin with +\fIformat-name\fR will be used while searching for an image data +format handler to read the data. +.TP +\fB\-from \fIx1 y1 x2 y2\fR +Specifies a rectangular sub-region of the image file data to be copied +to the destination image. If only \fIx1\fR and \fIy1\fR are +specified, the region extends from (\fIx1,y1\fR) to the bottom-right +corner of the image in the image file. If all four coordinates are +specified, they specify diagonally opposite corners or the region. +The default, if this option is not specified, is the whole of the +image in the image file. +.TP +\fB\-shrink\fR +If this option, the size of \fIimageName\fR will be reduced, if +necessary, so that the region into which the image file data are read +is at the bottom-right corner of the \fIimageName\fR. This option +will not affect the width or height of the image if the user has +specified a non-zero value for the \fB\-width\fR or \fB\-height\fR +configuration option, respectively. +.TP +\fB\-to \fIx y\fR +Specifies the coordinates of the top-left corner of the region of +\fIimageName\fR into which data from \fIfilename\fR are to be read. +The default is (0,0). +.RE +.TP +\fIimageName \fBredither\fR +The dithering algorithm used in displaying photo images propagates +quantization errors from one pixel to its neighbors. +If the image data for \fIimageName\fR is supplied in pieces, the +dithered image may not be exactly correct. Normally the difference is +not noticeable, but if it is a problem, this command can be used to +recalculate the dithered image in each window where the image is +displayed. +.TP +\fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR? +Writes image data from \fIimageName\fR to a file named \fIfilename\fR. +The following options may be specified: +.RS +.TP +\fB\-format\fI format-name\fR +Specifies the name of the image file format handler to be used to +write the data to the file. Specifically, this subcommand searches +for the first handler whose name matches a initial substring of +\fIformat-name\fR and which has the capability to write an image +file. If this option is not given, this subcommand uses the first +handler that has the capability to write an image file. +.TP +\fB\-from \fIx1 y1 x2 y2\fR +Specifies a rectangular region of \fIimageName\fR to be written to the +image file. If only \fIx1\fR and \fIy1\fR are specified, the region +extends from \fI(x1,y1)\fR to the bottom-right corner of +\fIimageName\fR. If all four coordinates are given, they specify +diagonally opposite corners of the rectangular region. The default, +if this option is not given, is the whole image. +.RE +.SH "IMAGE FORMATS" +.PP +The photo image code is structured to allow handlers for additional +image file formats to be added easily. The photo image code maintains +a list of these handlers. Handlers are added to the list by +registering them with a call to \fBTk_CreatePhotoImageFormat\fR. The +standard Tk distribution comes with handlers for PPM/PGM and GIF formats, +which are automatically registered on initialization. +.PP +When reading an image file or processing +string data specified with the \fB\-data\fR configuration option, the +photo image code invokes each handler in turn until one is +found that claims to be able to read the data in the file or string. +Usually this will find the correct handler, but if it doesn't, the +user may give a format name with the \fB\-format\fR option to specify +which handler to use. In fact the photo image code will try those +handlers whose names begin with the string specified for the +\fB\-format\fR option (the comparison is case-insensitive). For +example, if the user specifies \fB\-format gif\fR, then a handler +named GIF87 or GIF89 may be invoked, but a handler +named JPEG may not (assuming that such handlers had been +registered). +.PP +When writing image data to a file, the processing of the +\fB\-format\fR option is slightly different: the string value given +for the \fB\-format\fR option must begin with the complete name of the +requested handler, and may contain additional information following +that, which the handler can use, for example, to specify which variant +to use of the formats supported by the handler. + +.SH "COLOR ALLOCATION" +.PP +When a photo image is displayed in a window, the photo image code +allocates colors to use to display the image and dithers the image, if +necessary, to display a reasonable approximation to the image using +the colors that are available. The colors are allocated as a color +cube, that is, the number of colors allocated is the product of the +number of shades of red, green and blue. +.PP +Normally, the number of +colors allocated is chosen based on the depth of the window. For +example, in an 8-bit PseudoColor window, the photo image code will +attempt to allocate seven shades of red, seven shades of green and +four shades of blue, for a total of 198 colors. In a 1-bit StaticGray +(monochrome) window, it will allocate two colors, black and white. In +a 24-bit DirectColor or TrueColor window, it will allocate 256 shades +each of red, green and blue. Fortunately, because of the way that +pixel values can be combined in DirectColor and TrueColor windows, +this only requires 256 colors to be allocated. If not all of the +colors can be allocated, the photo image code reduces the number of +shades of each primary color and tries again. +.PP +The user can exercise some control over the number of colors that a +photo image uses with the \fB\-palette\fR configuration option. If +this option is used, it specifies the maximum number of shades of +each primary color to try to allocate. It can also be used to force +the image to be displayed in shades of gray, even on a color display, +by giving a single number rather than three numbers separated by +slashes. + +.SH CREDITS +.PP +The photo image type was designed and implemented by Paul Mackerras, +based on his earlier photo widget and some suggestions from +John Ousterhout. + +.SH KEYWORDS +photo, image, color |