1 files changed, 475 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/Photo.pod b/Master/tlpkg/tlperl/lib/Tk/Photo.pod
new file mode 100644
index 00000000000..02a691d6261
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/Photo.pod
@@ -0,0 +1,475 @@
+#  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.
+#  RCS: @(#) $Id: photo.n,v 1.2 1998/09/14 18:22:59 stanton Exp $
+#
+
+=head1 NAME
+
+Tk::Photo - Full-color images
+
+=for category Tk Image Classes
+
+=head1 SYNOPSIS
+
+S<    >I<$widget>-E<gt>B<Photo>(?I<name>??, I<options>?)
+
+=head1 DESCRIPTION
+
+A photo is an L<image|Tk::Image> whose pixels can display any color or be
+transparent.  A photo image is stored internally in full color (32
+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,
+XBM, XPM, BMP, JPEG, PNG 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
+or where it has been set transparent by the B<transparencySet>
+subcommand.
+
+=head1 CREATING PHOTOS
+
+Photos are created using the B<Photo> method.
+B<Photo> supports the following I<options>:
+
+=over 4
+
+=item B<-data> =E<gt> I<string>
+
+Specifies the contents of the image as a string.
+The string can
+contain base64 encoded data or binary data.
+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 B<-data>
+and B<-file> options are specified, the B<-file> option takes
+precedence.
+
+=item B<-format> =E<gt> I<format-name>
+
+Specifies the name of the file format for the data specified with the
+B<-data> or B<-file> option.
+
+=item B<-file> =E<gt> I<name>
+
+I<name> 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.
+
+=item B<-gamma> =E<gt> I<value>
+
+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.
+
+=item B<-height> =E<gt> I<number>
+
+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.
+
+=item B<-palette> =E<gt> I<palette-spec>
+
+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
+I<palette-spec> 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).
+
+=item B<-width> =E<gt> I<number>
+
+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.
+
+=back
+
+=head1 IMAGE METHODS
+
+When a photo image is created, Tk also creates a new object.
+This object supports the B<configure> and B<cget> methods
+described in L<Tk::options> which can be used to enquire and
+modify the options described above.
+
+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
+B<-width> and/or B<-height> configuration options, in which
+case the width and/or height, respectively, of the image will not be
+changed.
+
+The following addition methods are available for photo images:
+
+=over 4
+
+=item I<$image>-E<gt>B<blank>
+
+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.
+
+=item I<$image>-E<gt>B<copy>(I<sourceImage> ?,I<option value(s) ...>?)
+
+Copies a region from the image called I<$sourceImage> (which must
+be a photo image) to the image called I<$image>, possibly with
+pixel zooming and/or subsampling.  If no options are specified, this
+method copies the whole of I<$sourceImage> into I<$image>,
+starting at coordinates (0,0) in I<$image>.  The following
+options may be specified:
+
+=over 8
+
+=item B<-from> =E<gt> I<x1, y1, ? ,x2, y2?>
+
+Specifies a rectangular sub-region of the source image to be copied.
+(I<x1,y1>) and (I<x2,y2>) specify diagonally opposite corners of
+the rectangle.  If I<x2> and I<y2> 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 B<-from>
+option is not given, the default is the whole source image.
+
+=item B<-to> =E<gt> I<x1, y1, ?, x2, y2?>
+
+Specifies a rectangular sub-region of the destination image to be
+affected.  (I<x1,y1>) and (I<x2,y2>) specify diagonally opposite
+corners of the rectangle.  If I<x2> and I<y2> are not specified,
+the default value is (I<x1,y1>) plus the size of the source
+region (after subsampling and zooming, if specified).  If I<x2> and
+I<y2> are specified, the source region will be replicated if
+necessary to fill the destination region in a tiled fashion.
+
+=item B<-shrink>
+
+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
+B<-width> or B<-height> configuration option, respectively.
+
+=item B<-zoom> =E<gt> I<x, y>
+
+Specifies that the source region should be magnified by a factor of
+I<x> in the X direction and I<y> in the Y direction.  If I<y>
+is not given, the default value is the same as I<x>.  With this
+option, each pixel in the source image will be expanded into a block
+of I<x> x I<y> pixels in the destination image, all the same
+color.  I<x> and I<y> must be greater than 0.
+
+=item B<-subsample> =E<gt> I<x, y>
+
+Specifies that the source image should be reduced in size by using
+only every I<x>th pixel in the X direction and I<y>th pixel in
+the Y direction.  Negative values will cause the image to be flipped
+about the Y or X axes, respectively.  If I<y> is not given, the
+default value is the same as I<x>.
+
+=item B<-compositingrule> =E<gt> I<rule>
+
+Specifies how transparent pixels in the source image are combined with
+the destination image.  When a compositing rule of I<overlay> is
+set, the old contents of the destination image are visible, as if the
+source image were printed on a piece of transparent film and placed
+over the top of the destination.  When a compositing rule of I<set>
+is set, the old contents of the destination image are discarded and
+the source image is used as-is.  The default compositing rule is
+I<overlay>.
+
+=back
+
+=item I<$image>-E<gt>B<data>(?I<option value(s), ...>?)
+
+Returns image data in the form of a string.
+The following options may be specified:
+
+=over 8
+
+=item B<-background> =E<gt> I< color>
+
+If the color is specified, the data will not contain any transparency
+information. In all transparent pixels the color will be replaced by
+the specified color.
+
+=item B<-format> =E<gt> I<format-name>
+
+Specifies the name of the image file format handler to be used.
+Specifically, this method searches
+for the first handler whose name matches a initial substring of
+I<format-name> and which has the capability to read this image data.
+If this option is not given, this method uses the first
+handler that has the capability to read the image data.
+
+=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?>
+
+Specifies a rectangular region of I<$image> to be 
+returned.  If only I<x1> and I<y1> are specified, the region
+extends from I<(x1,y1)> to the bottom-right corner of
+I<$image>.  If all four coordinates are given, they specify
+diagonally opposite corners of the rectangular region, including x1,y1
+and excluding x2,y2.  The default,
+if this option is not given, is the whole image.
+
+=item B<-grayscale>
+
+If this options is specified, the data will not contain color
+information. All pixel data will be transformed into grayscale.
+
+=back
+
+=item I<$image>-E<gt>B<get>(I<x, y>)
+
+Returns the color of the pixel at coordinates (I<x>,I<y>) in the
+image as a list of three integers between 0 and 255, representing the
+red, green and blue components respectively.
+
+=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?>?)
+
+Sets pixels in I<$image> to the data specified in I<data>.
+This command first searches the list of image file format handlers for
+a handler that can interpret the data in I<data>, and then reads
+the image encoded within into I<$image> (the destination image).
+If I<data> does not match any known format, an attempt to interpret
+it as a (top-to-bottom) list of scan-lines is made, with each
+scan-line being a (left-to-right) list of pixel colors (see
+B<Tk_GetColor> for a description of valid colors.)  Every scan-line
+must be of the same length.  Note that when I<data> is a single
+color name, you are instructing Tk to fill a rectangular region with
+that color.  The following options may be specified:
+
+=over 4
+
+=item B<-format> =E<gt>I<format-name>
+
+Specifies the format of the image data in I<data>.
+Specifically, only image file format handlers whose names begin with
+I<format-name> will be used while searching for an image data
+format handler to read the data.
+
+=item B<-to> =E<gt>I<x, y> ?I<, x2, y2>?
+
+Specifies the coordinates of the top-left corner (I<x1>,I<y1>)
+of the region of I<$image> into which data from I<filename>
+are to be read.  The default is (0,0).  If I<x2>,I<y2> is given
+and I<data> is not large enough to cover the rectangle specified by
+this option, the image data extracted will be tiled so it covers the
+entire destination rectangle.  Note that if I<data> specifies a
+single color value, then a region extending to the bottom-right corner
+represented by (I<x2>,I<y2>) will be filled with that color.
+
+=back
+
+=item I<$image>-E<gt>B<read>(I<filename> ?,I<option value(s), ...>?)
+
+Reads image data from the file named I<filename> into the image.
+This method first searches the list of
+image file format handlers for a handler that can interpret the data
+in I<filename>, and then reads the image in I<filename> into
+I<$image> (the destination image).  The following options may be
+specified:
+
+=over 8
+
+=item B<-format> =E<gt> I<format-name>
+
+Specifies the format of the image data in I<filename>.
+Specifically, only image file format handlers whose names begin with
+I<format-name> will be used while searching for an image data
+format handler to read the data.
+
+=item B<-from> =E<gt> I<x1, y1, x2, y2>
+
+Specifies a rectangular sub-region of the image file data to be copied
+to the destination image.  If only I<x1> and I<y1> are
+specified, the region extends from (I<x1,y1>) 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.
+
+=item B<-shrink>
+
+If this option is specified, the size of I<$image> 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 I<$image>.  This option
+will not affect the width or height of the image if the user has
+specified a non-zero value for the B<-width> or B<-height>
+configuration option, respectively.
+
+=item B<-to> =E<gt> I<x, y>
+
+Specifies the coordinates of the top-left corner of the region of
+I<$image> into which data from I<filename> are to be read.
+The default is (0,0).
+
+=back
+
+=item I<$image>-E<gt>B<redither>
+
+The dithering algorithm used in displaying photo images propagates
+quantization errors from one pixel to its neighbors.
+If the image data for I<$image> 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 method can be used to
+recalculate the dithered image in each window where the image is
+displayed.
+
+=item I<$image>-E<gt>B<transparency>(I<subcommand, ?arg, arg ...?>);
+
+Allows examination and manipulation of the transparency information in
+the photo image.  Several subcommands are available:
+
+=over 4
+
+=item I<$image>-E<gt>B<transparencyGet>(I<x, y>);
+
+Returns a boolean indicating if the pixel at (I<x>,I<y>) is
+transparent.
+
+=item I<$image>-E<gt>B<transparencySet>(I<x, y, boolean>);
+
+Makes the pixel at (I<x>,I<y>) transparent if I<boolean> is
+true, and makes that pixel opaque otherwise.
+
+=back
+
+=item I<$image>-E<gt>B<write>(I<filename> ?,I<option value(s), ...>?)
+
+Writes image data from I<$image> to a file named I<filename>.
+The following options may be specified:
+
+=over 8
+
+=item B<-background> =E<gt> I< color>
+
+If the color is specified, the data will not contain any transparency
+information. In all transparent pixels the color will be replaced by
+the specified color.
+
+=item B<-format> =E<gt> I<format-name>
+
+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
+I<format-name> 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.
+
+=item B<-from> =E<gt> I<x1, y1, ?, x2, y2?>
+
+Specifies a rectangular region of I<$image> to be written to the
+image file.  If only I<x1> and I<y1> are specified, the region
+extends from I<(x1,y1)> to the bottom-right corner of
+I<$image>.  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.
+
+
+=item B<-grayscale>
+
+If this options is specified, the data will not contain color
+information. All pixel data will be transformed into grayscale.
+
+=back
+
+=back
+
+=head1 IMAGE FORMATS
+
+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 B<Tk_CreatePhotoImageFormat>.  The
+standard Tk distribution comes with handlers for XBM, XPM, BMP, JPEG,
+PNG and PPM/PGM formats, which are automatically registered on
+initialization.
+
+When reading an image file or processing
+string data specified with the B<-data> 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 B<-format> 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
+B<-format> option (the comparison is case-insensitive).  For
+example, if the user specifies B<-format> B<=E<gt>> B<gif>, then a handler
+named GIF87 or GIF89 may be invoked, but a handler
+named JPEG may not (assuming that such handlers had been
+registered).
+
+When writing image data to a file, the processing of the
+B<-format> option is slightly different: the string value given
+for the B<-format> 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.
+Note that not all image handlers may support writing transparency data
+to a file, even where the target image format does.
+
+=head1 COLOR ALLOCATION
+
+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.
+
+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.
+
+The user can exercise some control over the number of colors that a
+photo image uses with the B<-palette> 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.
+
+=head1 CREDITS
+
+The photo image type was designed and implemented by Paul Mackerras,
+based on his earlier photo widget and some suggestions from
+John Ousterhout.
+
+=head1 SEE ALSO
+
+L<Tk::Bitmap|Tk::Bitmap>
+L<Tk::Image|Tk::Image>
+L<Tk::Pixmap|Tk::Pixmap>
+
+=head1 KEYWORDS
+
+photo, image, color
+
+=cut
+
+