* doc/CrtImgType.3:

	* doc/CrtPhImgFmt.3:
	* doc/FindPhoto.3:
	* doc/photo.n: new docs for Img patch mods


FossilOrigin-Name: 29af8fe0ba72ae2e99c7c5705c00bcc9611e3477

4 files changed, 107 insertions, 42 deletions

diff --git a/doc/CrtImgType.3 b/doc/CrtImgType.3
index e705f95..918e0cc 100644
--- a/doc/CrtImgType.3
+++ b/doc/CrtImgType.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtImgType.3,v 1.2 1998/09/14 18:22:46 stanton Exp $
+'\" RCS: @(#) $Id: CrtImgType.3,v 1.3 1999/10/29 03:57:40 hobbs Exp $
 '\" 
 .so man.macros
 .TH Tk_CreateImageType 3 8.0 Tk "Tk Library Procedures"
@@ -109,8 +109,8 @@ an image of the new type.
 typedef int Tk_ImageCreateProc(
 	Tcl_Interp *\fIinterp\fR,
 	char *\fIname\fR,
-	int \fIargc\fR,
-	char **\fIargv\fR,
+	int \fIobjc\fR,
+	Tcl_Obj *CONST \fIobjv\fR[],
 	Tk_ImageType *\fItypePtr\fR,
 	Tk_ImageMaster \fImaster\fR,
 	ClientData *\fImasterDataPtr\fR);
@@ -119,13 +119,13 @@ The \fIinterp\fR argument is the interpreter in which the \fBimage\fR
 command was invoked, and \fIname\fR is the name for the new image,
 which was either specified explicitly in the \fBimage\fR command
 or generated automatically by the \fBimage\fR command.
-The \fIargc\fR and \fIargv\fR arguments describe all the configuration
+The \fIobjc\fR and \fIobjv\fR arguments describe all the configuration
 options for the new image (everything after the name argument to
 \fBimage\fR).
 The \fImaster\fR argument is a token that refers to Tk's information
 about this image;  the image manager must return this token to
 Tk when invoking the \fBTk_ImageChanged\fR procedure.
-Typically \fIcreateProc\fR will parse \fIargc\fR and \fIargv\fR
+Typically \fIcreateProc\fR will parse \fIobjc\fR and \fIobjv\fR
 and create an image master data structure for the new image.
 \fIcreateProc\fR may store an arbitrary one-word value at
 *\fImasterDataPtr\fR, which will be passed back to the
diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3
index 0689387..94b1404 100644
--- a/doc/CrtPhImgFmt.3
+++ b/doc/CrtPhImgFmt.3
@@ -9,7 +9,7 @@
 '\"	    Department of Computer Science,
 '\"	    Australian National University.
 '\"
-'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.2 1998/09/14 18:22:47 stanton Exp $
+'\" RCS: @(#) $Id: CrtPhImgFmt.3,v 1.3 1999/10/29 03:57:40 hobbs Exp $
 '\"
 .so man.macros
 .TH Tk_CreatePhotoImageFormat 3 4.0 Tk "Tk Library Procedures"
@@ -87,13 +87,14 @@ suitable for reading data in a given file.
 typedef int Tk_ImageFileMatchProc(
 	Tcl_Channel \fIchan\fR,
 	char *\fIfileName\fR,
-	char *\fIformatString\fR,
+	Tcl_Obj *\fIformat\fR,
 	int *\fIwidthPtr\fR,
-	int *\fIheightPtr\fR);
+	int *\fIheightPtr\fR,
+	Tcl_Interp *\fIinterp\fR);
 .CE
 The \fIfileName\fR argument is the name of the file containing the
 image data, which is open for reading as \fIchan\fR.  The
-\fIformatString\fR argument contains the value given for the
+\fIformat\fR argument contains the value given for the
 \fB\-format\fR option, or NULL if the option was not specified.
 If the data in the file appears to be in the format supported by this
 handler, the \fIformatPtr->fileMatchProc\fR procedure should store the
@@ -108,12 +109,13 @@ suitable for reading data from a given string.
 .CS
 typedef int Tk_ImageStringMatchProc(
 	char *\fIstring\fR,
-	char *\fIformatString\fR,
+	Tcl_Obj *\fIformat\fR,
 	int *\fIwidthPtr\fR,
-	int *\fIheightPtr\fR);
+	int *\fIheightPtr\fR,
+	Tcl_Interp *\fIinterp\fR);
 .CE
 The \fIstring\fR argument points to the string containing the image
-data.  The \fIformatString\fR argument contains the value given for
+data.  The \fIformat\fR argument contains the value given for
 the \fB\-format\fR option, or NULL if the option was not specified.
 If the data in the string appears to be in the format supported by
 this handler, the \fIformatPtr->stringMatchProc\fR procedure should
@@ -130,7 +132,7 @@ typedef int Tk_ImageFileReadProc(
 	Tcl_Interp *\fIinterp\fR,
 	Tcl_Channel \fIchan\fR,
 	char *\fIfileName\fR,
-	char *\fIformatString\fR,
+	Tcl_Obj *\fIformat\fR,
 	PhotoHandle \fIimageHandle\fR,
 	int \fIdestX\fR, int \fIdestY\fR,
 	int \fIwidth\fR, int \fIheight\fR,
@@ -139,7 +141,7 @@ typedef int Tk_ImageFileReadProc(
 The \fIinterp\fR argument is the interpreter in which the command was
 invoked to read the image; it should be used for reporting errors.
 The image data is in the file named \fIfileName\fR, which is open for
-reading as \fIchan\fR.  The \fIformatString\fR argument contains the
+reading as \fIchan\fR.  The \fIformat\fR argument contains the
 value given for the \fB\-format\fR option, or NULL if the option was
 not specified.  The image data in the file, or a subimage of it, is to
 be read into the photo image identified by the handle
@@ -158,7 +160,7 @@ Tk to call to read data from a string into a photo image.
 typedef int Tk_ImageStringReadProc(
 	Tcl_Interp *\fIinterp\fR,
 	char *\fIstring\fR,
-	char *\fIformatString\fR,
+	Tcl_Obj *\fIformat\fR,
 	PhotoHandle \fIimageHandle\fR,
 	int \fIdestX\fR, int \fIdestY\fR,
 	int \fIwidth\fR, int \fIheight\fR,
@@ -167,7 +169,7 @@ typedef int Tk_ImageStringReadProc(
 The \fIinterp\fR argument is the interpreter in which the command was
 invoked to read the image; it should be used for reporting errors.
 The \fIstring\fR argument points to the image data in string form.
-The \fIformatString\fR argument contains the
+The \fIformat\fR argument contains the
 value given for the \fB\-format\fR option, or NULL if the option was
 not specified.  The image data in the string, or a subimage of it, is to
 be read into the photo image identified by the handle
@@ -186,7 +188,7 @@ Tk to call to write data from a photo image to a file.
 typedef int Tk_ImageFileWriteProc(
 	Tcl_Interp *\fIinterp\fR,
 	char *\fIfileName\fR,
-	char *\fIformatString\fR,
+	Tcl_Obj *\fIformat\fR,
 	Tk_PhotoImageBlock *\fIblockPtr\fR);
 .CE
 The \fIinterp\fR argument is the interpreter in which the command was
@@ -195,7 +197,7 @@ The image data to be written are in memory and are described by the
 Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
 manual page FindPhoto(3) for details.  The \fIfileName\fR argument
 points to the string giving the name of the file in which to write the
-image data.  The \fIformatString\fR argument contains the
+image data.  The \fIformat\fR argument contains the
 value given for the \fB\-format\fR option, or NULL if the option was
 not specified.  The format string can contain extra characters
 after the name of the format.  If appropriate, the
@@ -211,7 +213,7 @@ Tk to call to translate image data from a photo image into a string.
 typedef int Tk_ImageStringWriteProc(
 	Tcl_Interp *\fIinterp\fR,
 	Tcl_DString *\fIdataPtr\fR,
-	char *\fIformatString\fR,
+	Tcl_Obj *\fIformat\fR,
 	Tk_PhotoImageBlock *\fIblockPtr\fR);
 .CE
 The \fIinterp\fR argument is the interpreter in which the command was
@@ -220,7 +222,7 @@ The image data to be converted are in memory and are described by the
 Tk_PhotoImageBlock structure pointed to by \fIblockPtr\fR; see the
 manual page FindPhoto(3) for details.  The data for the string
 should be appended to the dynamic string given by \fIdataPtr\fR.
-The \fIformatString\fR argument contains the
+The \fIformat\fR argument contains the
 value given for the \fB\-format\fR option, or NULL if the option was
 not specified.  The format string can contain extra characters
 after the name of the format.  If appropriate, the
diff --git a/doc/FindPhoto.3 b/doc/FindPhoto.3
index 0673efb..47f5df2 100644
--- a/doc/FindPhoto.3
+++ b/doc/FindPhoto.3
@@ -9,7 +9,7 @@
 '\"	    Department of Computer Science,
 '\"	    Australian National University.
 '\"
-'\" RCS: @(#) $Id: FindPhoto.3,v 1.2 1998/09/14 18:22:47 stanton Exp $
+'\" RCS: @(#) $Id: FindPhoto.3,v 1.3 1999/10/29 03:57:40 hobbs Exp $
 '\"
 .so man.macros
 .TH Tk_FindPhoto 3 8.0 Tk "Tk Library Procedures"
@@ -119,7 +119,7 @@ typedef struct {
 	int \fIheight\fR;
 	int \fIpitch\fR;
 	int \fIpixelSize\fR;
-	int \fIoffset[3]\fR;
+	int \fIoffset[4]\fR;
 } Tk_PhotoImageBlock;
 .CE
 The \fIpixelPtr\fR field points to the first pixel, that is, the
@@ -130,10 +130,10 @@ difference between two horizontally adjacent pixels.  Often it is 3
 or 4, but it can have any value.  The \fIpitch\fR field specifies the
 address difference between two vertically adjacent pixels.  The
 \fIoffset\fR array contains the offsets from the address of a pixel
-to the addresses of the bytes containing the red, green and blue
-components.  These are normally 0, 1 and 2, but can have other values,
-e.g., for images that are stored as separate red, green and blue
-planes.
+to the addresses of the bytes containing the red, green, blue and alpha
+(transparency) components.  These are normally 0, 1, 2 and 3, but can
+have other values, e.g., for images that are stored as separate red,
+green and blue planes.
 .PP
 The value given for the \fIwidth\fR and \fIheight\fR parameters to
 \fBTk_PhotoPutBlock\fR do not have to correspond to the values specified
diff --git a/doc/photo.n b/doc/photo.n
index b03ccf8..b9f143b 100644
--- a/doc/photo.n
+++ b/doc/photo.n
@@ -9,7 +9,7 @@
 '\"	    Department of Computer Science,
 '\"	    Australian National University.
 '\"
-'\" RCS: @(#) $Id: photo.n,v 1.2 1998/09/14 18:22:59 stanton Exp $
+'\" RCS: @(#) $Id: photo.n,v 1.3 1999/10/29 03:57:40 hobbs Exp $
 '\" 
 .so man.macros
 .TH photo n 4.0 Tk "Tk Built-In Commands"
@@ -24,7 +24,7 @@ photo \- Full-color images
 .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
+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
@@ -186,25 +186,78 @@ 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 \fBdata ?\fIoption value(s) ...\fR?
+Returns image data in the form of a string. The following options
+may be specified:
+.RS
+.TP
+\fB\-background\fI color\fR
+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.
+.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.
+.TP
+\fB\-grayscale\fR
+If this options is specified, the data will not contain color
+information. All pixel data will be transformed into grayscale.
+.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.
+\fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR?
+Sets pixels in \fI imageName\fR to the data specified in
+\fIdata\fR. This command first searches the list of image file
+format handlers for a handler that can interpret the data
+in \fIdata\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 \fIdata\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
+returned. 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.
+.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 \fBread\fR \fIfilename\fR ?\fIoption value(s) ...\fR?
 Reads image data from the file named \fIfilename\fR into the image.
@@ -258,6 +311,11 @@ Writes image data from \fIimageName\fR to a file named \fIfilename\fR.
 The following options may be specified:
 .RS
 .TP
+\fB\-background\fI color\fR
+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.
+.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
@@ -273,7 +331,12 @@ 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.
+.TP
+\fB\-grayscale\fR
+If this options is specified, the data will not contain color
+information. All pixel data will be transformed into grayscale.
 .RE
+.TP
 .SH "IMAGE FORMATS"
 .PP
 The photo image code is structured to allow handlers for additional