Initial revision

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