Reference implementation of TIP 166, rev. 1.9

1 files changed, 88 insertions, 13 deletions

diff --git a/doc/photo.n b/doc/photo.n
index 84cf618..287ed02 100644
--- a/doc/photo.n
+++ b/doc/photo.n
@@ -276,8 +276,8 @@ information. All pixel data will be transformed into grayscale.
 \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.
+image as a list of four integers between 0 and 255, representing the
+red, green, blue and alpha components respectively.
 .TP
 \fIimageName \fBput\fR \fIdata\fR ?\fIoption value(s) ...\fR?
 .
@@ -287,11 +287,58 @@ a handler that can interpret the data in \fIdata\fR, and then reads
 the image encoded within into \fIimageName\fR (the destination image).
 If \fIdata\fR 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
-\fBTk_GetColor\fR for a description of valid colors.)  Every scan-line
-must be of the same length.  Note that when \fIdata\fR is a single
-color name, you are instructing Tk to fill a rectangular region with
-that color.  The following options may be specified:
+scan-line being a (left-to-right) list of pixel data. Every scan-line
+must be of the same length. Pixel data is a color specification 
+optionally followed by a suffix giving the pixel's alpha value.
+The color of a pixel may be specified in any of these forms:
+.RS
+.IP \(bu 3
+The empty string - the pixel shall be fully transparent. In this case
+no alpha suffix is allowed.
+.IP \(bu 3
+Any value accepted by \fBTk_GetColor\fR.
+.IP \(bu 3
+A Tcl list with three or four integers in the range 0 to 255, 
+specifying the values for the red, green, bule and (optionally) 
+alpha channels respectively.
+.IP \(bu 3
+\fB#\fR\fIARGB\fR format: a \fB#\fR followed by four hexadecimal digits,
+where each digit is the value for the alpha, red, green and blue 
+channels respectively. Each digit will be expanded internally to 
+8-bits by multiplication by 0x11.
+.IP \(bu 3
+\fB#\fR\fIAARRGGBB\fR format: \fB#\fR followed by eight hexadecimal digits,
+where two subsequent digits represent the value for the alpha, red, green
+and blue channels respectively.
+.RE
+.sp
+The alpha value of a pixel can be specified by appending a prefix to the color
+specification. If no value for alpha is passed, the pixel is made fully 
+opaque. It is an error to append an alpha suffix to a color format that 
+already specifies an alpha value. The alpha suffix can have one of these 
+forms:
+.RS
+.TP
+\fB@\fR\fIA\fR
+.
+The alpha value \fIA\fR must be a fractional value in the range  0.0 
+(fully transparent) to 1.0 (fully opaque).
+.TP
+\fB#\fR\fIX\fR
+.
+The alpha value \fIX\fR is a hexadecimal digit that specifies an integer
+alpha value in the range 0 (fully transparent) to 255 (fully opaque). 
+This is expanded in range from 4 bits wide to 8 bits wide by 
+multiplication by 0x11.
+.TP
+\fB#\fR\fIXX\fR
+.
+The alpha value \fIXX\fR is passed as two hexadecimal digits that 
+specify an integer alpha value in the range 0 (fully transparent) to 255 
+(fully opaque). 
+.RE
+.sp
+The following options may be specified:
 .RS
 .TP
 \fB\-format \fIformat-name\fR
@@ -308,7 +355,9 @@ of the region of \fIimageName\fR into which the image data will be
 copied.  The default position is (0,0).  If \fIx2\fR,\fIy2\fR is given
 and \fIdata\fR 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 \fIdata\fR specifies a
+entire destination rectangle. If the region specified with this opion
+is smaller than the supplied \fIdata\fR, the exceeding data is silently
+discarded. Note that if \fIdata\fR specifies a
 single color value, then a region extending to the bottom-right corner
 represented by (\fIx2\fR,\fIy2\fR) will be filled with that color.
 .RE
@@ -372,15 +421,41 @@ Allows examination and manipulation of the transparency information in
 the photo image.  Several subcommands are available:
 .RS
 .TP
-\fIimageName \fBtransparency get \fIx y\fR
+\fIimageName \fBtransparency get \fIx y\fR ?\fIoption\fR?
 .
-Returns a boolean indicating if the pixel at (\fIx\fR,\fIy\fR) is
+Returns information about the transparency of the pixel at (\fIx\fR,\fIy\fR).
+At most one of the following options may be specified. If no option is
+passed, \fB-boolean\fR is implied:
+.RS
+.TP
+\fB-alpha\fR
+.
+The return value is the integral alpha value (in the range 0 to 255) for 
+the specified pixel.
+.TP
+\fB-boolean\fR
+.
+The return value is a boolean indicating if the specified pixel is fully
 transparent.
+.RE
 .TP
-\fIimageName \fBtransparency set \fIx y boolean\fR
+\fIimageName \fBtransparency set \fIx y\fR ?\fIoption\fR? \fInewVal\fR
 .
-Makes the pixel at (\fIx\fR,\fIy\fR) transparent if \fIboolean\fR is
-true, and makes that pixel opaque otherwise.
+Change the transparency of the pixel at (\fIx\fR,\fIy\fR).
+At most one of the following options may be specified. If no option is 
+passed, \fB-boolean\fR is implied:
+.RS
+.TP
+\fB-alpha\fR
+.
+Set the transparency of the specified pixel to \fInewVal\fR, which must be
+an integral value in the range 0 to 255.
+.TP
+\fB-boolean\fR
+.
+\fInewVal\fR will be interpreted as a boolean. If true, make the specified 
+pixel fully transparent, opaque otherwise.
+.RE
 .RE
 .TP
 \fIimageName \fBwrite \fIfilename\fR ?\fIoption value(s) ...\fR?