\documentclass[]{article}
\usepackage{amsmath,graphicx,supertabular,hyperref,tabularx,ifthen}
\title{TIP \#116: More Safety for Large Images}
\date{October 28, 2002}
\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 \#116}&\textbf{More Safety for Large Images}\\\hline
Author&

Donal K. Fellows \tipmail{donal.k.fellows}{man.ac.uk}
\\
Created&Monday, \(\text{28}^{\text{th}}\) October 2002\\
Type&Project\\
Tcl Version&\(8.5\)\\
State&Final\\
Vote&Done\\
Version&\tipversion$Revision: 1.6 $\\
Post History&\\
\hline\end{tabularx}\end{center}
\thispagestyle{empty}\pagestyle{empty}
\begin{tipabstract}

This TIP alters the C API for Tk's images so that failures to allocate sufficient memory for a large image can be handled more gracefully than a straight \textit{panic()}.
\end{tipabstract}
\tableofcontents\setcounter{page}{0}\clearpage\pagestyle{plain}

\section{Rationale}

Tk's image mechanism is nice and flexible, but it can run into problems with a large image. If we consider a square image that is 2000 pixels on each side (such sizes of images are becoming more common with the increasing popularity and sophistication of digital photography), we find it requires about 16MB of memory to load (4 million pixels, four bytes per pixel) but obviously just because an application fails to load that image (or something even larger), it doesn't mean that the best course of action is a \textit{panic()}-induced crash. Instead, a graceful failure back to the Tcl interpreter would allow for scripts to find a way to report this low-memory situation in a way that users can understand.

The problem with this is that for many of the routes through the Tk image API, there is no way to report a memory allocation failure; currently, the only failure mode is total. This TIP changes this.

\section{Proposed Changes}

I propose making the following functions that currently return \textit{void} return \textit{int} instead and that they should additionally take a standard \textit{Tcl\_Interp *interp} argument to allow an error message describing the failure (currently only due to insufficient memory) to be added to the current interpreter. It will not be an error for the \textit{interp} argument to be \textit{NULL}, though it will be up to the caller to guess why the failure happened.
\begin{itemize}
\item{}
\textit{Tk\_PhotoExpand} will become:
\begingroup\small\begin{verbatim}
int
Tk_PhotoExpand(Tcl_Interp *interp, Tk_PhotoHandle handle,
               int width, int height)
\end{verbatim}
\endgroup
\item{}
\textit{Tk\_PhotoPutBlock} will become:
\begingroup\small\begin{verbatim}
int
Tk_PhotoPutBlock(Tcl_Interp *interp, Tk_PhotoHandle handle,
                 Tk_PhotoImageBlock *blockPtr,
                 int x, int y, int width, int height, int compRule)
\end{verbatim}
\endgroup
\item{}
\textit{Tk\_PhotoPutZoomedBlock} will become:
\begingroup\small\begin{verbatim}
int
Tk_PhotoPutZoomedBlock(Tcl_Interp *interp, Tk_PhotoHandle handle,
                       Tk_PhotoImageBlock *blockPtr,
                       int x, int y, int width, int height,
                       int zoomX, int zoomY, int subsampleX, int subsampleY,
                       int compRule)
\end{verbatim}
\endgroup
\item{}
\textit{Tk\_PhotoSetSize} will become:
\begingroup\small\begin{verbatim}
int
Tk_PhotoSetSize(Tcl_Interp *interp, Tk_PhotoHandle handle,
                int width, int height)
\end{verbatim}
\endgroup
\end{itemize}

Also note that as a consequence of this, some image-related Tk commands will also gain additional error return situations. Since these all trigger abnormal process termination (and potentially a core-dump too) at the moment, this change in behaviour is believed to be wholly beneficial.

\section{Backward Compatibility}

This TIP also proposes a backward compatibility interface, so that extensions need not be heavily modified to work with new versions of Tk. This is done by leaving backwardly-compatible functions in the old locations in Tk's stub table and adding a \textit{\#define} to allow selection of the old API with the standard names. I propose doing this when the symbol \textit{USE\_PANIC\_ON\_PHOTO\_ALLOC\_FAILURE} is defined; like this, extension authors can switch from compiling with Tk 8.4 to using later versions by adding just one flag to their makefile (or other build script/environment.)

Note that this interacts with the backward-compatability interface defined in \cite{tip98}; if that is enabled, the back-compat interface defined here is enabled as well.

\section{Sample Implementation}

\url{http://sf.net/tracker/?func=detail&aid=646382&group_id=12997&atid=312997}

\section{Copyright}

This document has been 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 \#98]{tip98}
Donal K. Fellows,
\emph{Adding Transparency Compositing Rules to Photo Images},
on-line at \url{http://purl.org/tcl/tip/98.html}
\end{thebibliography}
\end{document}
