diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CrtPhImgFmt.3 | 294 | ||||
| -rw-r--r-- | doc/photo.n | 88 |
2 files changed, 349 insertions, 33 deletions
diff --git a/doc/CrtPhImgFmt.3 b/doc/CrtPhImgFmt.3 index 92f2441..c7accdb 100644 --- a/doc/CrtPhImgFmt.3 +++ b/doc/CrtPhImgFmt.3 @@ -9,7 +9,7 @@ '\" Department of Computer Science, '\" Australian National University. '\" -.TH Tk_CreatePhotoImageFormat 3 8.5 Tk "Tk Library Procedures" +.TH Tk_CreatePhotoImageFormat 3 8.7 Tk "Tk Library Procedures" .so man.macros .BS .SH NAME @@ -18,15 +18,23 @@ Tk_CreatePhotoImageFormat \- define new file format for photo images .nf \fB#include <tk.h>\fR .sp +.VS 8.7 +\fBTk_CreatePhotoImageFormatVersion3\fR(\fIformatVersion3Ptr\fR) +.VE 8.7 +.sp \fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) .SH ARGUMENTS -.AS "const Tk_PhotoImageFormat" *formatPtr +.AS "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr +.VS 8.7 +.AP "const Tk_PhotoImageFormatVersion3" *formatVersion3Ptr in +Structure that defines the new file format including metadata functionality. +.VE 8.7 .AP "const Tk_PhotoImageFormat" *formatPtr in Structure that defines the new file format. .BE .SH DESCRIPTION .PP -\fBTk_CreatePhotoImageFormat\fR is invoked to define a new file format +\fBTk_CreatePhotoImageFormatVersion3\fR is invoked to define a new file format for image data for use with photo images. The code that implements an image file format is called an image file format handler, or handler for short. The photo image code @@ -38,22 +46,29 @@ The user can specify which handler to use with the \fB\-format\fR image configuration option or the \fB\-format\fR option to the \fBread\fR and \fBwrite\fR photo image subcommands. .PP +The alternate version 2 function \fBTk_CreatePhotoImageFormat\fR has +identical functionality, but does not allow the handler to get or return +the metadata dictionary of the image. +It is described in section \fBVERSION 2 INTERFACE\fR below. +.PP An image file format handler consists of a collection of procedures -plus a Tk_PhotoImageFormat structure, which contains the name of the -image file format and pointers to six procedures provided by the -handler to deal with files and strings in this format. The -Tk_PhotoImageFormat structure contains the following fields: +plus a \fBTk_PhotoImageFormatVersion3\fR structure, which contains the +name of the image file format and pointers to six procedures provided +by the handler to deal with files and strings in this format. The +Tk_PhotoImageFormatVersion3 structure contains the following fields: +.VS 8.7 .CS -typedef struct Tk_PhotoImageFormat { +typedef struct Tk_PhotoImageFormatVersion3 { const char *\fIname\fR; - Tk_ImageFileMatchProc *\fIfileMatchProc\fR; - Tk_ImageStringMatchProc *\fIstringMatchProc\fR; - Tk_ImageFileReadProc *\fIfileReadProc\fR; - Tk_ImageStringReadProc *\fIstringReadProc\fR; - Tk_ImageFileWriteProc *\fIfileWriteProc\fR; - Tk_ImageStringWriteProc *\fIstringWriteProc\fR; -} \fBTk_PhotoImageFormat\fR; + Tk_ImageFileMatchProcVersion3 *\fIfileMatchProc\fR; + Tk_ImageStringMatchProcVersion3 *\fIstringMatchProc\fR; + Tk_ImageFileReadProcVersion3 *\fIfileReadProc\fR; + Tk_ImageStringReadProcVersion3 *\fIstringReadProc\fR; + Tk_ImageFileWriteProcVersion3 *\fIfileWriteProc\fR; + Tk_ImageStringWriteProcVersion3 *\fIstringWriteProc\fR; +} \fBTk_PhotoImageFormatVersion3\fR; .CE +.VE 8.7 .PP The handler need not provide implementations of all six procedures. For example, the procedures that handle string data would not be @@ -67,14 +82,16 @@ procedure, and the \fIstringMatchProc\fR procedure if it provides the .SS NAME .PP \fIformatPtr->name\fR provides a name for the image type. -Once \fBTk_CreatePhotoImageFormat\fR returns, this name may be used -in the \fB\-format\fR photo image configuration and subcommand option. +Once \fBTk_CreatePhotoImageFormatVersion3\fR returns, this name may be +used in the \fB\-format\fR photo image configuration and subcommand +option. The manual page for the photo image (photo(n)) describes how image file formats are chosen based on their names and the value given to the \fB\-format\fR option. The first character of \fIformatPtr->name\fR must not be an uppercase character from the ASCII character set (that is, one of the characters \fBA\fR-\fBZ\fR). Such names are used only for legacy interface support (see below). +.VS 8.7 .SS FILEMATCHPROC .PP \fIformatPtr->fileMatchProc\fR provides the address of a procedure for @@ -82,39 +99,47 @@ Tk to call when it is searching for an image file format handler suitable for reading data in a given file. \fIformatPtr->fileMatchProc\fR must match the following prototype: .CS -typedef int \fBTk_ImageFileMatchProc\fR( +typedef int \fBTk_ImageFileMatchProcVersion3\fR( + Tcl_Interp *\fIinterp\fR, Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + Tcl_Obj *\fImetadataOut\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 \fIformat\fR argument contains the value given for the \fB\-format\fR option, or NULL if the option was not specified. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. If the data in the file appears to be in the format supported by this handler, the \fIformatPtr->fileMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and *\fIheightPtr\fR respectively, and return 1. Otherwise it should return 0. .SS STRINGMATCHPROC .PP -\fIformatPtr->stringMatchProc\fR provides the address of a procedure for -Tk to call when it is searching for an image file format handler for +\fIformatPtr->stringMatchProc\fR provides the address of a procedure +for Tk to call when it is searching for an image file format handler suitable for reading data from a given string. \fIformatPtr->stringMatchProc\fR must match the following prototype: .CS -typedef int \fBTk_ImageStringMatchProc\fR( +typedef int \fBTk_ImageStringMatchProcVersion3\fR( + Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, int *\fIwidthPtr\fR, int *\fIheightPtr\fR, - Tcl_Interp *\fIinterp\fR); + Tcl_Obj *\fImetadataOut\fR); .CE The \fIdata\fR argument points to the object containing 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. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. If the data in the string appears to be in the format supported by this handler, the \fIformatPtr->stringMatchProc\fR procedure should store the width and height of the image in *\fIwidthPtr\fR and @@ -131,10 +156,12 @@ typedef int \fBTk_ImageFileReadProc\fR( Tcl_Channel \fIchan\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + int \fIsrcX\fR, int \fIsrcY\fR, + Tcl_Obj *\fImetadataOut\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was invoked to read the image; it should be used for reporting errors. @@ -148,34 +175,40 @@ dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. The return value is a standard Tcl return value. .SS STRINGREADPROC .PP -\fIformatPtr->stringReadProc\fR provides the address of a procedure for -Tk to call to read data from a string into a photo image. +\fIformatPtr->stringReadProc\fR provides the address of a procedure +for Tk to call to read data from a string into a photo image. \fIformatPtr->stringReadProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringReadProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIdata\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, PhotoHandle \fIimageHandle\fR, int \fIdestX\fR, int \fIdestY\fR, int \fIwidth\fR, int \fIheight\fR, - int \fIsrcX\fR, int \fIsrcY\fR); + int \fIsrcX\fR, int \fIsrcY\fR, + Tcl_Obj *\fImetadataOut\fR); .CE 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 \fIdata\fR argument points to the image data in object form. 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 +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 \fIimageHandle\fR. The subimage of the data in the string is of dimensions \fIwidth\fR x \fIheight\fR and has its top-left corner at coordinates (\fIsrcX\fR,\fIsrcY\fR). It is to be stored in the photo image with its top-left corner at coordinates (\fIdestX\fR,\fIdestY\fR) using the \fBTk_PhotoPutBlock\fR procedure. +\fBmetadataIn\fR and \fBmetadataOut\fR inputs and returns a metadata +dictionary as described in section \fBMETADATA INTERFACE\fR below. The return value is a standard Tcl return value. .SS FILEWRITEPROC .PP @@ -187,6 +220,7 @@ typedef int \fBTk_ImageFileWriteProc\fR( Tcl_Interp *\fIinterp\fR, const char *\fIfileName\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was @@ -201,16 +235,20 @@ not specified. The format string can contain extra characters after the name of the format. If appropriate, the \fIformatPtr->fileWriteProc\fR procedure may interpret these characters to specify further details about the image file. +\fBmetadataIn\fR may contain metadata keys that a driver may include +into the output data. The return value is a standard Tcl return value. .SS STRINGWRITEPROC .PP -\fIformatPtr->stringWriteProc\fR provides the address of a procedure for -Tk to call to translate image data from a photo image into a string. +\fIformatPtr->stringWriteProc\fR provides the address of a procedure +for Tk to call to translate image data from a photo image into a +string. \fIformatPtr->stringWriteProc\fR must match the following prototype: .CS typedef int \fBTk_ImageStringWriteProc\fR( Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIformat\fR, + Tcl_Obj *\fImetadataIn\fR, Tk_PhotoImageBlock *\fIblockPtr\fR); .CE The \fIinterp\fR argument is the interpreter in which the command was @@ -225,7 +263,201 @@ not specified. The format string can contain extra characters after the name of the format. If appropriate, the \fIformatPtr->stringWriteProc\fR procedure may interpret these characters to specify further details about the image file. +\fBmetadataIn\fR may contain metadata keys that a driver may include +into the output data. The return value is a standard Tcl return value. +.PP +.SH "METADATA INTERFACE" +.PP +Image formats contain a description of the image bitmap and may +contain additional information like image resolution or comments. +Image metadata may be read from image files and passed to the script +level by including dictionary keys into the metadata property of the +image. Image metadata may be written to image data on file write or +image data output. +.PP +.PP +.SS "METADATA KEYS" +.PP +The metadata may contain any key. +A driver will handle only a set of dictionary keys documented in the +documentation. See the photo image manual page for currently defined +keys for the system drivers. +.PP +The following rules may give guidance to name metadata keys: +.RS +Abreviation are in upper case +.RE +.RS +Words are in US English in small case (except proper nouns) +.RE +.RS +Vertical DPI is expressed as DPI/aspect. The reason is, that some +image formats may feature aspect and no resolution value. +.RE +.SS "METADATA INPUT" +.PP +Each driver function gets a Tcl object pointer \fBmetadataIn\fR as +parameter. This parameter serves to input a metadata dict to the +driver function. +It may be NULL to flag that the metadata dict is empty. +.PP +A typical driver code snipped to check for a metadata key is: +.CS +if (NULL != metadataIn) { + Tcl_Obj *itemData; + Tcl_DictObjGet(interp, metadataIn, Tcl_NewStringObj("Comment",-1), &itemData)); +.CE +.PP +The \-metadata command option data of the following commands is passed +to the driver: \fBimage create\fR, \fBconfigure\fR, \fBput\fR, +\fBread\fR, \fBdata\fR and \fBwrite\fR. +If no \-metadata command option available or not given, the metadata +property of the image is passed to the driver using the following +commands: \fBcget\fR, \fBconfigure\fR, \fBdata\fR and \fBwrite\fR. +.PP +Note that setting the \-metadata property of an image using +\fBconfigure\fR without any other option does not invoke any driver +function. +.PP +The metadata dictionary is not suited to pass options to the driver +related to the bitmap representation, as the image bitmap is not +recreated on a metadata change. The format string should be used for +this purpose. +.PP +.SS "METADATA OUTPUT" +.PP +The image match and read driver functions may set keys in a prepared +matadata dict to return them. +Those functions get a Tcl object pointer \fBmetadataOut\fR as +parameter. +metadataOut may be NULL to indicate, that no metadata return is +attended(\fBput\fR, \fBread\fR subcommands). +\fBmetadataOut\fR is initialized to an empty unshared dict object if +metadata return is attended (\fBimage create\fR command, \fBconfigure\fR +subcommand). The driver may set dict keys in this object to return +metadata. +If a match function succeeds, the metadataOut pointer is passed to the +corresponding read function. +.PP +A sample driver code snippet is: +.CS +if (NULL != metadataOut) { + Tcl_DictObjPut(NULL, metadataOut, Tcl_NewStringObj("XMP",-1), Tcl_NewStringObj(xmpMetadata); +.CE +.PP +The metadata keys returned by the driver are merged into the present +metadata property of the image or into the metadata dict given by the +\fB\-metadata\fR command line option. +At the script level, the command \fBimage create\fR and the +\fBconfigure\fR method may return metadata from the driver. +.PP +Format string options or metadata keys may influence the creation of +metadata within the driver. +For example, the creation of an expensive metadata key may depend on a +format string option or on a metadata input key. +.PP +.VE 8.7 +.SH "VERSION 2 INTERFACE" +.PP +Version 2 Interface does not include the possibility for the driver to +use the metadata dict for input or output. +.SS SYNOPSIS +\fB#include <tk.h>\fR +.sp +\fBTk_CreatePhotoImageFormat\fR(\fIformatPtr\fR) +.SS ARGUMENTS +.AS "const Tk_PhotoImageFormat" *formatPtr +.AP "const Tk_PhotoImageFormat" *formatPtr in +Structure that defines the new file format. +.BE +.SS DESCRIPTION +A driver using the version 2 interface invokes \fBTk_CreatePhotoImageFormat\fR +for driver registration. The Tk_PhotoImageFormat structure +contains the following fields: +.CS +typedef struct Tk_PhotoImageFormat { + const char *\fIname\fR; + Tk_ImageFileMatchProc *\fIfileMatchProc\fR; + Tk_ImageStringMatchProc *\fIstringMatchProc\fR; + Tk_ImageFileReadProc *\fIfileReadProc\fR; + Tk_ImageStringReadProc *\fIstringReadProc\fR; + Tk_ImageFileWriteProc *\fIfileWriteProc\fR; + Tk_ImageStringWriteProc *\fIstringWriteProc\fR; +} \fBTk_PhotoImageFormat\fR; +.CE +.PP +.SS FILEMATCHPROC +.PP +\fIformatPtr->fileMatchProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileMatchProc\fR( + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); +.CE +.PP +.SS STRINGMATCHPROC +.PP +\fIformatPtr->stringMatchProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringMatchProc\fR( + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + int *\fIwidthPtr\fR, + int *\fIheightPtr\fR, + Tcl_Interp *\fIinterp\fR); +.CE +.SS FILEREADPROC +.PP +\fIformatPtr->fileReadProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Channel \fIchan\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +.SS STRINGREADPROC +.PP +\fIformatPtr->stringReadProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringReadProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIdata\fR, + Tcl_Obj *\fIformat\fR, + PhotoHandle \fIimageHandle\fR, + int \fIdestX\fR, int \fIdestY\fR, + int \fIwidth\fR, int \fIheight\fR, + int \fIsrcX\fR, int \fIsrcY\fR); +.CE +.SS FILEWRITEPROC +.PP +\fIformatPtr->fileWriteProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageFileWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + const char *\fIfileName\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +.SS STRINGWRITEPROC +.PP +\fIformatPtr->stringWriteProc\fR must match the following prototype: +.CS +typedef int \fBTk_ImageStringWriteProc\fR( + Tcl_Interp *\fIinterp\fR, + Tcl_Obj *\fIformat\fR, + Tk_PhotoImageBlock *\fIblockPtr\fR); +.CE +.PP .SH "LEGACY INTERFACE SUPPORT" .PP In Tk 8.2 and earlier, the definition of all the function pointer diff --git a/doc/photo.n b/doc/photo.n index 3b206f5..f30039d 100644 --- a/doc/photo.n +++ b/doc/photo.n @@ -101,6 +101,16 @@ 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. +.VS 8.7 +.TP +\fB\-metadata \fImetadata\fR +. +Set the metadata dictionary of the image. +Additional keys may be set within the metadata dictionary of the image, +if image data is processed due to a \fB\-file\fR or \fB\-data\fR options +and the driver outputs any metadata keys. +See section \fBMETADATA DICTIONARY\fR below. +.VE 8.7 .TP \fB\-palette \fIpalette-spec\fR . @@ -146,7 +156,7 @@ The following commands are possible for photo images: . 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. +window it is displayed in will show through. The metadata dict of the image is not changed. .TP \fIimageName \fBcget\fR \fIoption\fR . @@ -169,6 +179,10 @@ 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\fR \fBphoto\fR command. +.VS 8.7 +Note: setting the \fB\-metadata\fR option without any other option +will not invoke the image format driver to recreate the bitmap. +.VE 8.7 .TP \fIimageName \fBcopy\fR \fIsourceImage\fR ?\fIoption value(s) ...\fR? . @@ -287,9 +301,18 @@ whole image. . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. -.RE .VS 8.7 .TP +\fB\-metadata\fR \fImetadata\fR +. +Image format handler may use metadata to be included in the returned +data string. +The specified \fImetadata\fR is passed to the driver for inclusion in the +data. +If no \fB\-metadata\fR option is given, the current metadata of the +image is used. +.VE 8.7 +.RE \fIimageName \fBget\fR \fIx y\fR ?\fB-withalpha\fR? . Returns the color of the pixel at coordinates (\fIx\fR,\fIy\fR) in the @@ -322,6 +345,15 @@ format handler to read the data. Note: the value of this option must be a Tcl list. This means that the braces may be omitted if the argument has only one word. Also, instead of braces, double quotes may be used for quoting. +.VS 8.7 +.TP +\fB\-metadata\fR \fImetadata\fR +. +A specified \fImetadata\fR is passed to the image format driver when interpreting +the data. +Note: The current metadata of the image is not passed to the format driver +and is not changed by the command. +.VE 8.7 .TP \fB\-to \fIx1 y1\fR ?\fIx2 y2\fR? . @@ -367,6 +399,15 @@ 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. +.VS 8.7 +.TP +\fB\-metadata\fR \fImetadata\fR +. +A specified \fImetadata\fR is passed to the image format driver when interpreting +the data. +Note: The current metadata of the image is not passed to the format driver +and is not changed by the command. +.VE 8.7 .TP \fB\-shrink\fR . @@ -460,6 +501,16 @@ if this option is not given, is the whole image. . If this options is specified, the data will not contain color information. All pixel data will be transformed into grayscale. +.VS 8.7 +.TP +\fB\-metadata\fR \fBmetadata\fR +. +Image format handler may use metadata to be included in the written file. +The specified \fImetadata\fR is passed to the driver for inclusion in the +file. +If no \fB\-metadata\fR option is given, the current metadata of the +image is used. +.VE 8.7 .RE .SH "IMAGE FORMATS" .PP @@ -682,6 +733,39 @@ 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. +.VS 8.7 +.SH "METADATA DICTIONARY" +.PP +Each image has a metadata dictionary property. +This dictionary is not relevant to the bitmap representation of the +image, but may contain additional information like resolution or +comments. +Image format drivers may output metadata when image data is +parsed, or may use metadata to be included in image files or formats. +.SS "METADATA KEYS" +.PP +Each image format driver supports an individual set of metadata dictionary +keys. Predefined keys are: +.TP +DPI +. +Horizontal image resolution in DPI as a double value. +Supported by format \fBpng\fR. +.TP +aspect +. +Aspect ratio horizontal divided by vertical as double value. +Supported by formats \fBgif\fR and \fBpng\fR. +.TP +comment +. +Image text comment. +Supported by formats \fBgif\fR and \fBpng\fR. +.PP +It is valid to set any key in the metadata dict. +A format driver will ignore keys it does not handle. +.PP +.VE 8.7 .SH CREDITS .PP The photo image type was designed and implemented by Paul Mackerras, |