428 lines
23 KiB
HTML
428 lines
23 KiB
HTML
|
<HTML><HEAD><TITLE>Tk Built-In Commands - photo manual page</TITLE></HEAD><BODY>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M2" NAME="L869">NAME</A>
|
||
|
|
<DL><DD>photo - Full-color images</DL>
|
||
|
|
<DD><A HREF="photo.htm#M3" NAME="L870">SYNOPSIS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><B>image create photo </B>?<I>name</I>? ?<I>options</I>?
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M4" NAME="L871">DESCRIPTION</A>
|
||
|
|
<DD><A HREF="photo.htm#M5" NAME="L872">CREATING PHOTOS</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M6" NAME="L873"><B>-data </B><I>string</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M7" NAME="L874"><B>-format </B><I>format-name</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M8" NAME="L875"><B>-file </B><I>name</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M9" NAME="L876"><B>-gamma </B><I>value</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M10" NAME="L877"><B>-height </B><I>number</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M11" NAME="L878"><B>-palette </B><I>palette-spec</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M12" NAME="L879"><B>-width </B><I>number</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M13" NAME="L880">IMAGE COMMAND</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M14" NAME="L881"><I>imageName </I><B>blank</B></A>
|
||
|
|
<DD><A HREF="photo.htm#M15" NAME="L882"><I>imageName </I><B>cget</B> <I>option</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M16" NAME="L883"><I>imageName </I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?</A>
|
||
|
|
<DD><A HREF="photo.htm#M17" NAME="L884"><I>imageName </I><B>copy</B> <I>sourceImage</I> ?<I>option value(s) ...</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M18" NAME="L885"><B>-from </B><I>x1 y1 x2 y2</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M19" NAME="L886"><B>-to </B><I>x1 y1 x2 y2</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M20" NAME="L887"><B>-shrink</B></A>
|
||
|
|
<DD><A HREF="photo.htm#M21" NAME="L888"><B>-zoom </B><I>x y</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M22" NAME="L889"><B>-subsample </B><I>x y</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M23" NAME="L890"><I>imageName </I><B>data ?</B><I>option value(s) ...</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M24" NAME="L891"><B>-background</B><I> color</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M25" NAME="L892"><B>-format</B><I> format-name</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M26" NAME="L893"><B>-from </B><I>x1 y1 x2 y2</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M27" NAME="L894"><B>-grayscale</B></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M28" NAME="L895"><I>imageName </I><B>get</B> <I>x y</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M29" NAME="L896"><I>imageName </I><B>put</B> <I>data</I> ?<I>option value(s) ...</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M30" NAME="L897"><B>-format </B><I>format-name</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M31" NAME="L898"><B>-from </B><I>x1 y1 x2 y2</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M32" NAME="L899"><B>-shrink</B></A>
|
||
|
|
<DD><A HREF="photo.htm#M33" NAME="L900"><B>-to </B><I>x y</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M34" NAME="L901"><I>imageName </I><B>read</B> <I>filename</I> ?<I>option value(s) ...</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M35" NAME="L902"><B>-format </B><I>format-name</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M36" NAME="L903"><B>-from </B><I>x1 y1 x2 y2</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M37" NAME="L904"><B>-shrink</B></A>
|
||
|
|
<DD><A HREF="photo.htm#M38" NAME="L905"><B>-to </B><I>x y</I></A>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M39" NAME="L906"><I>imageName </I><B>redither</B></A>
|
||
|
|
<DD><A HREF="photo.htm#M40" NAME="L907"><I>imageName </I><B>write </B><I>filename</I> ?<I>option value(s) ...</I>?</A>
|
||
|
|
<DL>
|
||
|
|
<DD><A HREF="photo.htm#M41" NAME="L908"><B>-background</B><I> color</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M42" NAME="L909"><B>-format</B><I> format-name</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M43" NAME="L910"><B>-from </B><I>x1 y1 x2 y2</I></A>
|
||
|
|
<DD><A HREF="photo.htm#M44" NAME="L911"><B>-grayscale</B></A>
|
||
|
|
</DL>
|
||
|
|
</DL>
|
||
|
|
<DD><A HREF="photo.htm#M45" NAME="L912">IMAGE FORMATS</A>
|
||
|
|
<DD><A HREF="photo.htm#M46" NAME="L913">COLOR ALLOCATION</A>
|
||
|
|
<DD><A HREF="photo.htm#M47" NAME="L914">CREDITS</A>
|
||
|
|
<DD><A HREF="photo.htm#M48" NAME="L915">KEYWORDS</A>
|
||
|
|
</DL><HR>
|
||
|
|
<H3><A NAME="M2">NAME</A></H3>
|
||
|
|
photo - Full-color images
|
||
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
||
|
|
<B>image create photo </B>?<I>name</I>? ?<I>options</I>?<BR>
|
||
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<H3><A NAME="M5">CREATING PHOTOS</A></H3>
|
||
|
|
Like all images, photos are created using the <B><A HREF="../TclCmd/image.htm">image create</A></B>
|
||
|
|
command.
|
||
|
|
Photos support the following <I>options</I>:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M6"><B>-data </B><I>string</I></A><DD>
|
||
|
|
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</B>
|
||
|
|
and <B>-file</B> options are specified, the <B>-file</B> option takes
|
||
|
|
precedence.
|
||
|
|
<P><DT><A NAME="M7"><B>-format </B><I>format-name</I></A><DD>
|
||
|
|
Specifies the name of the file format for the data specified with the
|
||
|
|
<B>-data</B> or <B>-file</B> option.
|
||
|
|
<P><DT><A NAME="M8"><B>-file </B><I>name</I></A><DD>
|
||
|
|
<I>name</I> 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.
|
||
|
|
<P><DT><A NAME="M9"><B>-gamma </B><I>value</I></A><DD>
|
||
|
|
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.
|
||
|
|
<P><DT><A NAME="M10"><B>-height </B><I>number</I></A><DD>
|
||
|
|
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.
|
||
|
|
<P><DT><A NAME="M11"><B>-palette </B><I>palette-spec</I></A><DD>
|
||
|
|
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</I> 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).
|
||
|
|
<P><DT><A NAME="M12"><B>-width </B><I>number</I></A><DD>
|
||
|
|
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.
|
||
|
|
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M13">IMAGE COMMAND</A></H3>
|
||
|
|
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:
|
||
|
|
<PRE><I>imageName option </I>?<I>arg arg ...</I>?</PRE>
|
||
|
|
<I>Option</I> and the <I>arg</I>s
|
||
|
|
determine the exact behavior of the command.
|
||
|
|
<P>
|
||
|
|
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</B> and/or <B>-height</B> configuration options, in which
|
||
|
|
case the width and/or height, respectively, of the image will not be
|
||
|
|
changed.
|
||
|
|
<P>
|
||
|
|
The following commands are possible for photo images:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M14"><I>imageName </I><B>blank</B></A><DD>
|
||
|
|
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.
|
||
|
|
<P><DT><A NAME="M15"><I>imageName </I><B>cget</B> <I>option</I></A><DD>
|
||
|
|
Returns the current value of the configuration option given
|
||
|
|
by <I>option</I>.
|
||
|
|
<I>Option</I> may have any of the values accepted by the
|
||
|
|
<B>image create photo</B> command.
|
||
|
|
<P><DT><A NAME="M16"><I>imageName </I><B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>?</A><DD>
|
||
|
|
Query or modify the configuration options for the image.
|
||
|
|
If no <I>option</I> is specified, returns a list describing all of
|
||
|
|
the available options for <I>imageName</I> (see <B><A HREF="../TclLib/ConfigWidg.htm">Tk_ConfigureInfo</A></B> for
|
||
|
|
information on the format of this list). If <I>option</I> is specified
|
||
|
|
with no <I>value</I>, 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 <I>option</I> is specified). If
|
||
|
|
one or more <I>option-value</I> 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.
|
||
|
|
<I>Option</I> may have any of the values accepted by the
|
||
|
|
<B>image create photo</B> command.
|
||
|
|
<P><DT><A NAME="M17"><I>imageName </I><B>copy</B> <I>sourceImage</I> ?<I>option value(s) ...</I>?</A><DD>
|
||
|
|
Copies a region from the image called <I>sourceImage</I> (which must
|
||
|
|
be a photo image) to the image called <I>imageName</I>, possibly with
|
||
|
|
pixel zooming and/or subsampling. If no options are specified, this
|
||
|
|
command copies the whole of <I>sourceImage</I> into <I>imageName</I>,
|
||
|
|
starting at coordinates (0,0) in <I>imageName</I>. The following
|
||
|
|
options may be specified:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M18"><B>-from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
|
|
Specifies a rectangular sub-region of the source image to be copied.
|
||
|
|
(<I>x1,y1</I>) and (<I>x2,y2</I>) specify diagonally opposite corners of
|
||
|
|
the rectangle. If <I>x2</I> and <I>y2</I> 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</B>
|
||
|
|
option is not given, the default is the whole source image.
|
||
|
|
<P><DT><A NAME="M19"><B>-to </B><I>x1 y1 x2 y2</I></A><DD>
|
||
|
|
Specifies a rectangular sub-region of the destination image to be
|
||
|
|
affected. (<I>x1,y1</I>) and (<I>x2,y2</I>) specify diagonally opposite
|
||
|
|
corners of the rectangle. If <I>x2</I> and <I>y2</I> are not specified,
|
||
|
|
the default value is (<I>x1,y1</I>) plus the size of the source
|
||
|
|
region (after subsampling and zooming, if specified). If <I>x2</I> and
|
||
|
|
<I>y2</I> are specified, the source region will be replicated if
|
||
|
|
necessary to fill the destination region in a tiled fashion.
|
||
|
|
<P><DT><A NAME="M20"><B>-shrink</B></A><DD>
|
||
|
|
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</B> or <B>-height</B> configuration option, respectively.
|
||
|
|
<P><DT><A NAME="M21"><B>-zoom </B><I>x y</I></A><DD>
|
||
|
|
Specifies that the source region should be magnified by a factor of
|
||
|
|
<I>x</I> in the X direction and <I>y</I> in the Y direction. If <I>y</I>
|
||
|
|
is not given, the default value is the same as <I>x</I>. With this
|
||
|
|
option, each pixel in the source image will be expanded into a block
|
||
|
|
of <I>x</I> x <I>y</I> pixels in the destination image, all the same
|
||
|
|
color. <I>x</I> and <I>y</I> must be greater than 0.
|
||
|
|
<P><DT><A NAME="M22"><B>-subsample </B><I>x y</I></A><DD>
|
||
|
|
Specifies that the source image should be reduced in size by using
|
||
|
|
only every <I>x</I>th pixel in the X direction and <I>y</I>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</I> is not given, the
|
||
|
|
default value is the same as <I>x</I>.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M23"><I>imageName </I><B>data ?</B><I>option value(s) ...</I>?</A><DD>
|
||
|
|
Returns image data in the form of a string. The following options
|
||
|
|
may be specified:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M24"><B>-background</B><I> color</I></A><DD>
|
||
|
|
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.
|
||
|
|
<P><DT><A NAME="M25"><B>-format</B><I> format-name</I></A><DD>
|
||
|
|
Specifies the name of the image file format handler to be used.
|
||
|
|
Specifically, this subcommand searches
|
||
|
|
for the first handler whose name matches a initial substring of
|
||
|
|
<I>format-name</I> and which has the capability to read this image data.
|
||
|
|
If this option is not given, this subcommand uses the first
|
||
|
|
handler that has the capability to read the image data.
|
||
|
|
<P><DT><A NAME="M26"><B>-from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
|
|
Specifies a rectangular region of <I>imageName</I> to be returned.
|
||
|
|
If only <I>x1</I> and <I>y1</I> are specified, the region
|
||
|
|
extends from <I>(x1,y1)</I> to the bottom-right corner of
|
||
|
|
<I>imageName</I>. 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.
|
||
|
|
<P><DT><A NAME="M27"><B>-grayscale</B></A><DD>
|
||
|
|
If this options is specified, the data will not contain color
|
||
|
|
information. All pixel data will be transformed into grayscale.
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M28"><I>imageName </I><B>get</B> <I>x y</I></A><DD>
|
||
|
|
Returns the color of the pixel at coordinates (<I>x</I>,<I>y</I>) in the
|
||
|
|
image as a list of three integers between 0 and 255, representing the
|
||
|
|
red, green and blue components respectively.
|
||
|
|
<P><DT><A NAME="M29"><I>imageName </I><B>put</B> <I>data</I> ?<I>option value(s) ...</I>?</A><DD>
|
||
|
|
Sets pixels in <I> imageName</I> to the data specified in
|
||
|
|
<I>data</I>. This command first searches the list of image file
|
||
|
|
format handlers for a handler that can interpret the data
|
||
|
|
in <I>data</I>, and then reads the image in <I>filename</I> into
|
||
|
|
<I>imageName</I> (the destination image). The following options
|
||
|
|
may be specified:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M30"><B>-format </B><I>format-name</I></A><DD>
|
||
|
|
Specifies the format of the image data in <I>data</I>.
|
||
|
|
Specifically, only image file format handlers whose names begin with
|
||
|
|
<I>format-name</I> will be used while searching for an image data
|
||
|
|
format handler to read the data.
|
||
|
|
<P><DT><A NAME="M31"><B>-from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
|
|
Specifies a rectangular sub-region of the image file data to be
|
||
|
|
returned. If only <I>x1</I> and <I>y1</I> are specified, the region
|
||
|
|
extends from (<I>x1,y1</I>) 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.
|
||
|
|
<P><DT><A NAME="M32"><B>-shrink</B></A><DD>
|
||
|
|
If this option, the size of <I>imageName</I> 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>imageName</I>. 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</B> or <B>-height</B>
|
||
|
|
configuration option, respectively.
|
||
|
|
<P><DT><A NAME="M33"><B>-to </B><I>x y</I></A><DD>
|
||
|
|
Specifies the coordinates of the top-left corner of the region of
|
||
|
|
<I>imageName</I> into which data from <I>filename</I> are to be read.
|
||
|
|
The default is (0,0).
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M34"><I>imageName </I><B>read</B> <I>filename</I> ?<I>option value(s) ...</I>?</A><DD>
|
||
|
|
Reads image data from the file named <I>filename</I> into the image.
|
||
|
|
This command first searches the list of
|
||
|
|
image file format handlers for a handler that can interpret the data
|
||
|
|
in <I>filename</I>, and then reads the image in <I>filename</I> into
|
||
|
|
<I>imageName</I> (the destination image). The following options may be
|
||
|
|
specified:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M35"><B>-format </B><I>format-name</I></A><DD>
|
||
|
|
Specifies the format of the image data in <I>filename</I>.
|
||
|
|
Specifically, only image file format handlers whose names begin with
|
||
|
|
<I>format-name</I> will be used while searching for an image data
|
||
|
|
format handler to read the data.
|
||
|
|
<P><DT><A NAME="M36"><B>-from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
|
|
Specifies a rectangular sub-region of the image file data to be copied
|
||
|
|
to the destination image. If only <I>x1</I> and <I>y1</I> are
|
||
|
|
specified, the region extends from (<I>x1,y1</I>) 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.
|
||
|
|
<P><DT><A NAME="M37"><B>-shrink</B></A><DD>
|
||
|
|
If this option, the size of <I>imageName</I> 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>imageName</I>. 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</B> or <B>-height</B>
|
||
|
|
configuration option, respectively.
|
||
|
|
<P><DT><A NAME="M38"><B>-to </B><I>x y</I></A><DD>
|
||
|
|
Specifies the coordinates of the top-left corner of the region of
|
||
|
|
<I>imageName</I> into which data from <I>filename</I> are to be read.
|
||
|
|
The default is (0,0).
|
||
|
|
<P></DL>
|
||
|
|
<P><DT><A NAME="M39"><I>imageName </I><B>redither</B></A><DD>
|
||
|
|
The dithering algorithm used in displaying photo images propagates
|
||
|
|
quantization errors from one pixel to its neighbors.
|
||
|
|
If the image data for <I>imageName</I> 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.
|
||
|
|
<P><DT><A NAME="M40"><I>imageName </I><B>write </B><I>filename</I> ?<I>option value(s) ...</I>?</A><DD>
|
||
|
|
Writes image data from <I>imageName</I> to a file named <I>filename</I>.
|
||
|
|
The following options may be specified:
|
||
|
|
<P>
|
||
|
|
<DL>
|
||
|
|
<P><DT><A NAME="M41"><B>-background</B><I> color</I></A><DD>
|
||
|
|
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.
|
||
|
|
<P><DT><A NAME="M42"><B>-format</B><I> format-name</I></A><DD>
|
||
|
|
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</I> 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.
|
||
|
|
<P><DT><A NAME="M43"><B>-from </B><I>x1 y1 x2 y2</I></A><DD>
|
||
|
|
Specifies a rectangular region of <I>imageName</I> to be written to the
|
||
|
|
image file. If only <I>x1</I> and <I>y1</I> are specified, the region
|
||
|
|
extends from <I>(x1,y1)</I> to the bottom-right corner of
|
||
|
|
<I>imageName</I>. 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.
|
||
|
|
<P><DT><A NAME="M44"><B>-grayscale</B></A><DD>
|
||
|
|
If this options is specified, the data will not contain color
|
||
|
|
information. All pixel data will be transformed into grayscale.
|
||
|
|
<P></DL>
|
||
|
|
<P></DL>
|
||
|
|
<H3><A NAME="M45">IMAGE FORMATS</A></H3>
|
||
|
|
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><A HREF="../TclLib/CrtPhImgFmt.htm">Tk_CreatePhotoImageFormat</A></B>. The
|
||
|
|
standard Tk distribution comes with handlers for PPM/PGM and GIF formats,
|
||
|
|
which are automatically registered on initialization.
|
||
|
|
<P>
|
||
|
|
When reading an image file or processing
|
||
|
|
string data specified with the <B>-data</B> 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</B> 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</B> option (the comparison is case-insensitive). For
|
||
|
|
example, if the user specifies <B>-format gif</B>, then a handler
|
||
|
|
named GIF87 or GIF89 may be invoked, but a handler
|
||
|
|
named JPEG may not (assuming that such handlers had been
|
||
|
|
registered).
|
||
|
|
<P>
|
||
|
|
When writing image data to a file, the processing of the
|
||
|
|
<B>-format</B> option is slightly different: the string value given
|
||
|
|
for the <B>-format</B> 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.
|
||
|
|
|
||
|
|
<H3><A NAME="M46">COLOR ALLOCATION</A></H3>
|
||
|
|
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.
|
||
|
|
<P>
|
||
|
|
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.
|
||
|
|
<P>
|
||
|
|
The user can exercise some control over the number of colors that a
|
||
|
|
photo image uses with the <B>-palette</B> 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.
|
||
|
|
|
||
|
|
<H3><A NAME="M47">CREDITS</A></H3>
|
||
|
|
The photo image type was designed and implemented by Paul Mackerras,
|
||
|
|
based on his earlier photo widget and some suggestions from
|
||
|
|
John Ousterhout.
|
||
|
|
|
||
|
|
<H3><A NAME="M48">KEYWORDS</A></H3>
|
||
|
|
<A href="../Keywords/P.htm#photo">photo</A>, <A href="../Keywords/I.htm#image">image</A>, <A href="../Keywords/C.htm#color">color</A>
|
||
|
|
<HR><PRE>
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994 The Australian National University
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1994-1997 Sun Microsystems, Inc.
|
||
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
||
|
|
</BODY></HTML>
|