NAME
       photo - Full-color images

SYNOPSIS
       image create photo ?name? ?options?


DESCRIPTION
       A  photo is an 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  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.


CREATING PHOTOS
       Like all images, photos are created using the image create
       command.  Photos support the following options:

       -data 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
              -data and -file options are  specified,  the  -file
              option takes precedence.

       -format format-name
              Specifies  the name of the file format for the data
              specified with the -data or -file option.

       -file name
              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.

       -gamma 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.

       -height 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.

       -palette 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 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).

       -width 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.


IMAGE COMMAND
       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:
              imageName option ?arg arg ...?
       Option and the args determine the exact  behavior  of  the
       command.

       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  -width  and/or  -height
       configuration  options,  in  which  case  the width and/or
       height, respectively, of the image will not be changed.

       The following commands are possible for photo images:

       imageName 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.

       imageName cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values  accepted by the image create photo command.

       imageName configure ?option? ?value option value ...?
              Query or modify the configuration options  for  the
              image.   If  no option is specified, returns a list
              describing  all  of  the  available   options   for
              imageName  (see Tk_ConfigureInfo for information on
              the format of this list).  If option  is  specified
              with  no  value,  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 option is  specified).   If  one  or
              more  option-value  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.  Option may have any of the values
              accepted by the image create photo command.

       imageName copy sourceImage ?option value(s) ...?
              Copies  a  region from the image called sourceImage
              (which must be a photo image) to the  image  called
              imageName,   possibly  with  pixel  zooming  and/or
              subsampling.  If no  options  are  specified,  this
              command   copies  the  whole  of  sourceImage  into
              imageName,  starting  at   coordinates   (0,0)   in
              imageName.  The following options may be specified:

              -from x1 y1 x2 y2
                     Specifies a rectangular  sub-region  of  the
                     source  image  to  be  copied.   (x1,y1) and
                     (x2,y2) specify diagonally opposite  corners
                     of  the  rectangle.   If  x2  and 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 -from  option
                     is  not  given,  the  default  is  the whole
                     source image.

              -to x1 y1 x2 y2
                     Specifies a rectangular  sub-region  of  the
                     destination  image  to be affected.  (x1,y1)
                     and  (x2,y2)  specify  diagonally   opposite
                     corners  of the rectangle.  If x2 and y2 are
                     not specified, the default value is  (x1,y1)
                     plus  the  size  of the source region (after
                     subsampling and zooming, if specified).   If
                     x2  and  y2 are specified, the source region
                     will be replicated if necessary to fill  the
                     destination region in a tiled fashion.

              -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  -width or -height
                     configuration option, respectively.

              -zoom x y
                     Specifies that the source region  should  be
                     magnified   by  a  factor  of  x  in  the  X
                     direction and y in the Y direction.  If y is
                     not  given, the default value is the same as
                     x.  With this  option,  each  pixel  in  the
                     source  image  will be expanded into a block
                     of x x y pixels in  the  destination  image,
                     all the same color.  x and y must be greater
                     than 0.

              -subsample x y
                     Specifies that the source  image  should  be
                     reduced  in  size  by  using  only every xth
                     pixel in the X direction and  yth  pixel  in
                     the Y direction.  Negative values will cause
                     the image to be flipped about  the  Y  or  X
                     axes,  respectively.  If y is not given, the
                     default value is the same as x.

       imageName data ?option value(s) ...?
              Returns image data in the form  of  a  string.  The
              following options may be specified:

              -background 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.

              -format 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  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.

              -from x1 y1 x2 y2
                     Specifies a rectangular region of  imageName
                     to be written to the image file.  If only x1
                     and y1 are  specified,  the  region  extends
                     from  (x1,y1)  to the bottom-right corner of
                     imageName.   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.

              -grayscale
                     If this options is specified, the data  will
                     not  contain  color  information.  All pixel
                     data will be transformed into grayscale.

       imageName get x y
              Returns the color of the pixel at coordinates (x,y)
              in  the image as a list of three integers between 0
              and 255,  representing  the  red,  green  and  blue
              components respectively.

       imageName put data ?option value(s) ...?
              Sets  pixels in  imageName to the data specified in
              data. This command first searches the list of image
              file   format  handlers  for  a  handler  that  can
              interpret the data in  data,  and  then  reads  the
              image  in  filename into imageName (the destination
              image). The following options may be specified:

              -format format-name
                     Specifies the format of the  image  data  in
                     data.   Specifically, only image file format
                     handlers whose names begin with  format-name
                     will  be  used  while searching for an image
                     data format handler to read the data.

              -from x1 y1 x2 y2
                     Specifies a rectangular  sub-region  of  the
                     image  file  data to be returned. If only x1
                     and y1 are  specified,  the  region  extends
                     from  (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.

              -shrink
                     If this option, the size of  imageName  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 imageName.
                     This option will not  affect  the  width  or
                     height   of   the  image  if  the  user  has
                     specified a non-zero value for the -width or
                     -height  configuration option, respectively.

              -to x y
                     Specifies the coordinates  of  the  top-left
                     corner of the region of imageName into which
                     data from filename  are  to  be  read.   The
                     default is (0,0).

       imageName read filename ?option value(s) ...?
              Reads  image data from the file named filename into
              the image.  This command first searches the list of
              image  file  format handlers for a handler that can
              interpret the data in filename, and then reads  the
              image  in  filename into imageName (the destination
              image).  The following options may be specified:

              -format format-name
                     Specifies the format of the  image  data  in
                     filename.   Specifically,  only  image  file
                     format  handlers  whose  names  begin   with
                     format-name will be used while searching for
                     an image data format  handler  to  read  the
                     data.

              -from x1 y1 x2 y2
                     Specifies  a  rectangular  sub-region of the
                     image  file  data  to  be  copied   to   the
                     destination  image.   If  only x1 and y1 are
                     specified, the region extends  from  (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.

              -shrink
                     If this option, the size of  imageName  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 imageName.
                     This option will not  affect  the  width  or
                     height   of   the  image  if  the  user  has
                     specified a non-zero value for the -width or
                     -height  configuration option, respectively.

              -to x y
                     Specifies the coordinates  of  the  top-left
                     corner of the region of imageName into which
                     data from filename  are  to  be  read.   The
                     default is (0,0).

       imageName redither
              The  dithering  algorithm  used in displaying photo
              images  propagates  quantization  errors  from  one
              pixel  to  its  neighbors.   If  the image data for
              imageName 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.

       imageName write filename ?option value(s) ...?
              Writes  image  data  from imageName to a file named
              filename.  The following options may be specified:

              -background 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.

              -format 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 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.

              -from x1 y1 x2 y2
                     Specifies  a rectangular region of imageName
                     to be written to the image file.  If only x1
                     and  y1  are  specified,  the region extends
                     from (x1,y1) to the bottom-right  corner  of
                     imageName.   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.

              -grayscale
                     If  this options is specified, the data will
                     not contain  color  information.  All  pixel
                     data will be transformed into grayscale.


       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   Tk_CreatePhotoImageFormat.   The  standard  Tk
       distribution comes  with  handlers  for  PPM/PGM  and  GIF
       formats,    which    are   automatically   registered   on
       initialization.

       When reading an  image  file  or  processing  string  data
       specified  with  the -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
       -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  -format  option
       (the comparison is case-insensitive).  For example, if the
       user specifies -format 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
       -format  option  is  slightly  different: the string value
       given for the -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.


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   -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.


CREDITS
       The photo image type was designed and implemented by  Paul
       Mackerras,  based  on  his  earlier  photo widget and some
       suggestions from John Ousterhout.


KEYWORDS
