\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#98: Adding Transparency Compositing Rules to Photo Images}
\date{June 09, 2001}
\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 \#98}&\textbf{Adding Transparency Compositing Rules to Photo Images}\\\hline
Author&

Donal K. Fellows \tipmail{fellowsd}{cs.man.ac.uk}
\\
Created&Saturday, \(\text{9}^{\text{th}}\) June 2001\\
Type&Project\\
Tcl Version&\(8.4\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.5 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP adds compositing rules to Tk's photo images to give programmers better control over what happens when two transparent images are combined. This TIP also allows for several frames of an animated GIF file to be correctly displayed in an image even when the transparent area is not constant.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

This is a TIP that is inspired by the tkchat application in Tcllib, and in particular by the image used to represent the LOL smiley. The problem with this image is that its transparent area changes over time, and this is caused by the fact that \textit{Tk\_PhotoPutBlock()} only allows one way of compositing a block with an image; it behaves as if the data being added was on a sheet of cel (the material used to make hand-drawn animated cartoons) allowing for sophisticated layering effects. Unfortunately, for many applications (and animated GIF images are definitely among these) this sophistication works against us. In a GIF image, transparency is treated not as extra information that is added to each pixel's colour, but rather as a special colour; a pixel cannot be, for example, red and transparent at the same time. Support for this requires a different (and indeed simpler) kind of compositing rule. And of course, once you have such a facility in the underlying C code, it should be exposed to scripts.

There are other kinds of compositing rule (for example, acting like the added block is placed under the image, and many others) but this TIP does not propose adding anything other than a way to chose between the current behaviour and the behaviour required for supporting GIF animation, in the belief that those two compositing rules are the ones most useful to programmers, and that once the general facility is there, the other rules will be relatively easy to add in the future.

\section{Specification}

This TIP adds a \textit{compositingRule} argument to \textit{Tk\_PhotoPutBlock} (and \textit{Tk\_PhotoPutZoomedBlock}) to allow selection between the current behaviour (overlaying) and the other one I wish to support (setting/overriding.) The permitted values of this argument will be \textit{TK\_PHOTO\_COMPOSITE\_OVERLAY} (the currently implemented behaviour) and \textit{TK\_PHOTO\_COMPOSITE\_SET} (the behaviour required to support GIF file animation.)

At the Tcl level, when copying from one image to another (the other photo image subcommands do not currently support transparency at all) the \textit{photo get} will take an extra option \textit{-compositingrule} to allow selection of the compositing rule. The permitted values of this option will be \textit{overlay} and \textit{set} by analogy with the values described above.

\section{Implementation Notes}

Proposed implementation patch: \url{https://sourceforge.net/tracker/index.php?func=detail&aid=566765&group_id=12997&atid=312997}

The proposed implementation of this TIP naturally includes backward-compatibility functions that allow pre-compiled extensions to continue to operate without recompilation (provided they use Stubs for linking.) Furthermore, extension authors can also define the symbol \textit{USE\_COMPOSITELESS\_PHOTO\_PUT\_BLOCK} when compiling and have source-level compatibility with the old functions.

The proposed implementation also creates \textit{TkSubtractRegion} as a new internal function; it is the analogue of \textit{XSubtractRegion} as \textit{TkIntersectRegion} is the analogue of \textit{XIntersectRegion}. It might be useful to other parts of the core that manipulate regions.

Both the PPM and GIF file readers use the \textit{set} compositing rule, PPM because the format does not support transparency (and \textit{set} should at least theoretically be faster) and GIF because it is required semantically. Other image formats are not required to do this, of course. The \textit{\$img put \$data} photo image subcommand uses \textit{set} compositing because it does not support transparency.

\section{Copyright}

This document is placed in the public domain.

\section{Colophon}

\textit{TIP AutoGenerator --- written by Donal K. Fellows}
\end{document}
