\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#14: Access to Tk Photo Image Transparency}
\date{November 22, 2000}
\author{Donal K. Fellows}
\urlstyle{sf}
\setlength{\parskip}{1ex}
\setlength{\parindent}{0pt}
\def\tipversion$#1${\texttt{\$#1\$}}
\def\tiplangle#1{\ensuremath{<}}
\def\tiprangle#1{\ensuremath{>}}
\def\tipbar#1{\ensuremath{|}}
\def\tipmail#1#2{\(\langle\){\small\expandafter\url{#1@#2}}\(\rangle\)}
\ifx\pdfoutput\undefined
\newcommand{\tipimage}[2]{\typeout{Make sure you download #1.eps}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.eps}}{\includegraphics[width=0.8\textwidth]{#1.eps}}}
\newcommand{\tipxref}[1]{}
\newcommand{\tipxrefend}{}
\else
\newcommand{\tipimage}[2]{\typeout{Make sure you create #1.pdf}\ifthenelse{\lengthtest{0.8\textwidth>#2}\and\lengthtest{0pt<#2}}{\includegraphics{#1.pdf}}{\includegraphics[width=0.8\textwidth]{#1.pdf}}}
\pdfcatalog{/PageMode /UseOutlines}
\newcommand{\tipxref}[1]{\pdfannotlink attr {/C [0.5 0.5 1.0] /Border [0 0 1]} goto name {#1}}
\newcommand{\tipxrefend}{\pdfendlink}
\fi
\newenvironment{tipabstract}{\begin{abstract}}{\end{abstract}}
\begin{document}\maketitle
\begin{center}\begin{tabularx}{\linewidth}{|r@{: }X|}\hline
\textbf{TIP \#14}&\textbf{Access to Tk Photo Image Transparency}\\\hline
Author&

Donal K. Fellows \tipmail{fellowsd}{cs.man.ac.uk}
\\
Created&Wednesday, \(\text{22}^{\text{nd}}\) November 2000\\
Type&Project\\
Tcl Version&\(8.4.0\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 2.5 $\\
Keywords&Tk, photo, transparency, internal, access\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

It is useful for some code (both extensions and scripts) to have access to the transparency information in photo images for various reasons, but this is not currently available, even via an internal structure defined in \textit{generic/tkInt.h}. This TIP is aimed at making the information available, and in such a way at the C level that backward compatibility is maintained in the future even if the internal structure definitions change.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

I have been working for several years (on-and-off) on an extension for Tk that allows it to have non-rectangular windows (\url{http://www.cs.man.ac.uk/~fellowsd/tcl/shapeidx.html}) which is an effect that is great for all sorts of purposes but which comes particularly into its own when used in conjunction with drag-and-drop to make drag tokens that obscure only part of what lies underneath them. However, one of the most useful ways of specifying the shape of a window turns out to be via images of various kinds, and the natural way to do this is with the transparency data within the image. The problem is that this data is locked up entirely within structures that are completely private to \textit{generic/tkImgPhoto.c}; none of it is visible at all anywhere else, even within the core. (There is code that uses colour data instead to do this sort of trick, \url{http://www.sys.uea.ac.uk/~fuzz/tktrans/default.html}, but this is a slow process and frankly a little strange if we already have transparency data available.)

There is also a more general need for scripts to be able to discover more about the transparent areas of a photo image; at the moment, there is no access at all to that information at the script level.

\section{Changes to the C-Level API}

To get around this problem, the data member \textit{validRegion} of the \textit{PhotoMaster} structure needs to be made available by some mechanism. There are two ways of doing this:
\begin{enumerate}
\item{}
Placing the \textit{PhotoMaster} structure, or some version of it, in \textit{generic/tkInt.h}, or
\setcounter{enumi}{1}
\item{}
Creating a function to access the data member.
\end{enumerate}

The first way is very cheap initially, but also very inflexible and creates yet another hidden version dependency (such as is tackled in \cite{tip5}) should we decide to change the structure for any reason (we also have had problems with this sort of thing in the past in relation to the \textit{Tcl\_Interp} member \textit{result}, direct access to which has been deprecated for years, but where there is still existing code that does it and which forms one of the largest barriers for some extensions from upgrading to Tcl 8.0 or later.) It is also unnecessary since only the core needs to know how to create new instances of the structure.

The second way, by contrast, is far more flexible in the future as it will allow us to completely change the internal implementation of photo image transparency without affecting any extensions at all. The cost of doing this is that a new entry in one of the stub tables must be created. Due to the fact that the type of the \textit{validRegion} member is (currently) internal, I propose adding the function to the \textit{tkInt} stub interface, and I propose calling the function \textit{TkPhotoGetValidRegion}.

\section{Changes to the Tcl-Level API}

I propose to add an extra subcommand to photo image instances which will provide all the access to and manipulation of transparency data. I propose to call this subcommand \textit{transparency} and it will have subsubcommands to provide access to the various facilities it provides. Initially I will provide a \textit{get} subsubcommand to allow the testing of the transparency of a single pixel (returned as a boolean value), and a \textit{set} subsubcommand to allow the setting of the transparency of a single pixel. I anticipate that these will be expanded in the future to allow the manipulation of transparencies of rectangular regions (both getting and setting) but I do not supply such at this stage.
\begingroup\small\begin{verbatim}
   image create photo phImg -file thingy.gif
   if {[phImg transparency get 0 0]} {
      # Top-left pixel is transparent...
   }

   # Toggle transparency...
   phImg transparency set 0 0 [expr {![phImg transparency get 0 0]}]
\end{verbatim}
\endgroup

\section{Sample Implementation Patches}

Exposing the transparency to C: \url{http://www.cs.man.ac.uk/~fellowsd/tcl/validRegion.patch}

Exposing the transparency to Tcl: \url{http://www.cs.man.ac.uk/~fellowsd/tcl/patches/transCmd.patch}

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\begin{thebibliography}{TIP \#1}
\addcontentsline{toc}{section}{References}
\bibitem[TIP \#5]{tip5}
Eric Melski,
\emph{Make TkClassProcs and TkSetClassProcs Public and Extensible},
on-line at \url{http://purl.org/tcl/tip/5.html}
\end{thebibliography}
\end{document}
