345 lines
16 KiB
Plaintext
345 lines
16 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1994 The Australian National University
|
|
'\" Copyright (c) 1994-1996 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.10 96/03/26 18:26:22"
|
|
'\"
|
|
.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 from a file.
|
|
.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
|