% -*- latex -*-

%\documentclass[pdf,ps2pdf,12pt,report,strict]{SANDreport}
\documentclass[12pt,report,strict]{SANDreport}
\usepackage{pslatex}
\usepackage[fancyhdr]{latex2man}
\usepackage{ifthen}
\usepackage{xspace}
\usepackage{relsize}
\usepackage{fancyvrb}

%%% % Comment this if not a draft.
%%% \usepackage[all,light]{draftcopy}

\usepackage{color}
\definecolor{yellow}{rgb}{1,1,0}
\definecolor{black}{rgb}{0,0,0}
\definecolor{ltcyan}{rgb}{.75,1,1}
\definecolor{red}{rgb}{1,0,0}

% This wonderful package allows hyphenation in tt fonts and hyphenation of
% words with underscores in them.
\usepackage[htt]{hyphenat}

\usepackage{makeidx}
\makeindex

\usepackage{hyperref}
\hypersetup{pdftitle={@TITLE@}}
\hypersetup{pdfauthor={Kenneth Moreland}}
% \hypersetup{colorlinks}
% \hypersetup{linkcolor=blue}
% \hypersetup{linkcolor=blue}
\hypersetup{breaklinks}
\hypersetup{pagebackref}
\hypersetup{pdfstartpage=3}

% -----------------------------------------------------------------------------
%
% Set the title, author, and date
%

\title{@TITLE@ \\
  \relsize{-2}Version @VERSION@
}
\author{Kenneth~Moreland \\
  Data Analysis and Visualization \\
  Sandia National Laboratories \\
  P.O. Box 5800  MS 1323 \\
  Albuquerque, NM  87185-1323 \\
  kmorel@sandia.gov
}

% There is a "Printed" date on the title page of a SAND report, so
% the generic \date should generally be empty.
\date{}

% -----------------------------------------------------------------------------
% Set some things we need for SAND reports. These are mandatory
%
\SANDnum{SANDXXXX-XXXX}
\SANDprintDate{XXX 2010}
\SANDauthor{Kenneth~Moreland}

% -----------------------------------------------------------------------------
% Include the markings required for the SAND report.  These are actually
% the default and not strictly necessary.
\SANDreleaseType{Unlimited Release}
\SANDmarkCover{Approved for public release; further dissemination unlimited.}

%-----------------------------------------------------------------------------
% The following definition does not have a default value and will not
% print anything, if not defined
\SANDsupersed{SAND2009-3170}{May 2009}

%-----------------------------------------------------------------------------
% Commands for inserting common words.
\newcommand{\IceT}{IceT\xspace}
\newcommand{\OpenGL}{\index{OpenGL}OpenGL\xspace}
\newcommand{\MPI}{\index{MPI}{MPI}\xspace}

% Commands for words with special meanings.
\newcommand*{\keyterm}[1]{\textbf{#1}}

\newcommand{\sticky}[1]{{\color{red}\textsc{[#1]}}}

\CustomVerbatimEnvironment{code}{Verbatim}{fontsize=\small}
\newcommand*{\codeinput}[2][]{%
  \VerbatimInput[fontsize=\small,#1]{#2}%
}

% A special section for man pages.  We don't really want these to show up
% in the table of contents.
% \newcommand{\mansection}[1]{
%   \\[\baselineskip]
%   \textbf{\textsc{\large #1}} \\[0.5\baselineskip]
% }
\makeatletter
\renewcommand{\subsection}{\@startsection
  {subsection}
  {2}
  {0mm}
  {-\baselineskip}
  {0.5\baselineskip}
  {\normalfont\large\bfseries\scshape}
}
\makeatother
\newcommand*{\mansection}[1]{\subsection*{#1}}  

% The latex2man Name environment does not mesh well with the SAND
% environment, nor is it designed to have several man pages in the same
% document.  Thus, we change it to fit.
\newcommand*{\currentmansection}{none}
\renewenvironment{Name}[5]{
  % #1 Man Chapter
  % #2 Name
  % #3 Author
  % #4 Tool
  % #5 Title
  \clearpage
  \renewcommand{\currentmansection}{#2}
  \index{\currentmansection|(textbf}
  \lhead[#2]{}
  \rhead[]{#2}
  \phantomsection
  \addcontentsline{toc}{section}{\currentmansection}
  \label{manpage:#2}
  \mansection{Name}
  #5
}{
  \index{\currentmansection|)}
}

% Change the latex2man Table environment.  Mostly to get rid of the
% indentation it places on the left hand side.  The nopagebreak option
% tries to avoid adding a page break (which can add a lot of space on the
% previous page).  The raggedbottom option says that if a page break is
% absolutely necessary, do not try to make the bottom of the previous page
% to the bottom of the page; it will add a bunch of space in the middle
% that will look bad.  The flush bottom option restores normal page flush
% operation.
\newlength{\tableindent}
\settowidth{\tableindent}{\enspace}
\addtolength{\tableindent}{\parindent}
\renewenvironment{Table}[1]{%
  \raggedbottom%
  \par\hspace*{-\tableindent}%
  \begin{tabular}{*{#1}{l}}%
}{%
  \end{tabular}%
  \nopagebreak[3]%
  \flushbottom%
  \par%
}

% Commands for typesetting C identifiers.
\newcommand{\textC}[1]{\texttt{#1}}                     % Basic C code.
\newcommand{\textCF}[1]{\textbf{\textC{#1}}}
\newcommand{\textCT}[1]{\textbf{\textC{#1}}}

\newcommand{\CType}[1]{\index{#1}\textCT{#1}}           % A documented type.
\newcommand{\CFunc}[2][!*!]{%                           % A documented function.
  % Only reference if not in that man section.
  \ifthenelse%
      {\equal{#1}{!*!}}%
      {\ifthenelse%
        {\equal{#2}{\currentmansection}}%
        {\textCF{#2}}%
        {\index{#2}\hyperref[manpage:#2]{\textCF{#2}}}%
      }%
      {\ifthenelse%
        {\equal{#1}{\currentmansection}}%
        {\textCF{#2}}%
        {\index{#1}\hyperref[manpage:#1]{\textCF{#2}}}%
      }%
}
\newcommand*{\CFuncExternal}[1]{%                       % An external function.
  \index{#1}%
  \textCF{#1}%
}
\newcommand*{\CFuncSeeAlso}[1]{%                        % A see also reference.
  \hyperref[manpage:#1]{\textCF{#1}}%
}
\newcommand*{\CTypeExternal}[1]{\CType{#1}}             % An external type.

\newcommand*{\CArg}[1]{\emph{\textC{#1}}}               % A function argument.
\newcommand*{\CEnum}[1]{\index{#1}\textbf{\textC{#1}}}  % A const enumeration.
\newcommand*{\CErrorEnum}[1]{\textbf{\textC{#1}}}       % An error constant.

% Functions that have aliases for cross referencing and indexing.
\newcommand{\icetBoundingBoxf}{\CFunc[icetBoundingBox]{icetBoundingBoxf}\xspace}
\newcommand{\icetBoundingBoxd}{\CFunc[icetBoundingBox]{icetBoundingBoxd}\xspace}

\newcommand{\icetEnable}{\CFunc[icetEnable]{icetEnable}\xspace}
\newcommand{\icetDisable}{\CFunc[icetEnable]{icetDisable}\xspace}

\newcommand{\icetGetBitFieldv}{\CFunc[icetGet]{icetGetBitFieldv}\xspace}
\newcommand{\icetGetBooleanv}{\CFunc[icetGet]{icetGetBooleanv}\xspace}
\newcommand{\icetGetDoublev}{\CFunc[icetGet]{icetGetDoublev}\xspace}
\newcommand{\icetGetEnumv}{\CFunc[icetGet]{icetGetEnumv}\xspace}
\newcommand{\icetGetFloatv}{\CFunc[icetGet]{icetGetFloatv}\xspace}
\newcommand{\icetGetIntegerv}{\CFunc[icetGet]{icetGetIntegerv}\xspace}
\newcommand{\icetGetPointerv}{\CFunc[icetGet]{icetGetPointerv}\xspace}

\newcommand{\icetSetColorFormat}{\CFunc{icetSetColorFormat}\xspace}
\newcommand{\icetSetDepthFormat}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetSetColorFormat}}%
    {\CFunc[icetSetColorFormat]{icetSetDepthFormat}}%
    {\CFunc{icetSetDepthFormat}}%
    \xspace%
}

\newcommand{\icetImageGetColorFormat}{\CFunc{icetImageGetColorFormat}\xspace}
\newcommand{\icetImageGetDepthFormat}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageGetColorFormat}}%
    {\CFunc[icetImageGetColorFormat]{icetImageGetDepthFormat}}%
    {\CFunc{icetImageGetDepthFormat}}%
    \xspace%
}

\newcommand{\icetImageGetNumPixels}{\CFunc{icetImageGetNumPixels}\xspace}
\newcommand{\icetImageGetWidth}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageGetNumPixels}}%
    {\CFunc[icetImageGetNumPixels]{icetImageGetWidth}}%
    {\CFunc{icetImageGetWidth}}%
    \xspace%
}
\newcommand{\icetImageGetHeight}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageGetNumPixels}}%
    {\CFunc[icetImageGetNumPixels]{icetImageGetHeight}}%
    {\CFunc{icetImageGetHeight}}%
    \xspace%
}

\newcommand{\icetImageGetColor}{\CFunc{icetImageGetColor}\xspace}
\newcommand{\icetImageGetColorub}{\CFunc[icetImageGetColor]{icetImageGetColorub}\xspace}
\newcommand{\icetImageGetColorui}{\CFunc[icetImageGetColor]{icetImageGetColorui}\xspace}
\newcommand{\icetImageGetColorf}{\CFunc[icetImageGetColor]{icetImageGetColorf}\xspace}

\newcommand{\icetImageGetDepth}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageGetColor}}%
    {\CFunc[icetImageGetColor]{icetImageGetDepth}}%
    {\CFunc{icetImageGetDepth}}%
    \xspace%
}
\newcommand{\icetImageGetDepthf}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageGetColor}}%
    {\CFunc[icetImageGetColor]{icetImageGetDepthf}}%
    {\CFunc[icetImageGetDepth]{icetImageGetDepthf}}%
    \xspace%
}

\newcommand{\icetImageCopyColor}{\CFunc{icetImageCopyColor}\xspace}
\newcommand{\icetImageCopyColorub}{\CFunc[icetImageCopyColor]{icetImageCopyColorub}\xspace}
\newcommand{\icetImageCopyColorf}{\CFunc[icetImageCopyColor]{icetImageCopyColorf}\xspace}

\newcommand{\icetImageCopyDepth}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageCopyColor}}%
    {\CFunc[icetImageCopyColor]{icetImageCopyDepth}}%
    {\CFunc{icetImageCopyDepth}}%
    \xspace%
}
\newcommand{\icetImageCopyDepthf}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageCopyColor}}%
    {\CFunc[icetImageCopyColor]{icetImageCopyDepthf}}%
    {\CFunc[icetImageCopyDepth]{icetImageCopyDepthf}}%
    \xspace%
}

\newcommand{\icetUnsafeStateGetDouble}{%
  \CFunc[icetUnsafeStateGet]{icetUnsafeStateGetDouble}\xspace%
}
\newcommand{\icetUnsafeStateGetFloat}{%
  \CFunc[icetUnsafeStateGet]{icetUnsafeStateGetFloat}\xspace%
}
\newcommand{\icetUnsafeStateGetInteger}{%
  \CFunc[icetUnsafeStateGet]{icetUnsafeStateGetInteger}\xspace%
}
\newcommand{\icetUnsafeStateGetBoolean}{%
  \CFunc[icetUnsafeStateGet]{icetUnsafeStateGetBoolean}\xspace%
}
\newcommand{\icetUnsafeStateGetPointer}{%
  \CFunc[icetUnsafeStateGet]{icetUnsafeStateGetPointer}\xspace%
}

%-----------------------------------------------------------------------------
% The actual document.

\begin{document}

\sloppy
\maketitle

% An abstract is required for SAND reports.

\begin{abstract}
  The Image Composition Engine for Tiles (\IceT) is a high-performance
  sort-last parallel rendering library.  In addition to providing
  accelerated rendering for a standard display, \IceT provides the unique
  ability to generate images for tiled displays.  The overall resolution of
  the display may be several times larger than any viewport that may be
  rendered by a single machine.  This document is an overview of the user
  interface to \IceT.
\end{abstract}

%-----------------------------------------------------------------------------
% In case we every need an acknowledgement section.
\clearpage
\chapter*{Acknowledgement}

I would like to thank Brian Wylie.  It was his ``big ideas'' that got the
ball rolling on the \IceT algorithms and library, and it was his continuing
vision that pushed us on this path to parallel rendering.

I would also like to thank the folks at Kitware, Inc. for adopting the
\IceT library as the parallel rendering library for ParaView.  They also
maintain the \IceT code repository.  Without them, \IceT would probably be
collecting dust on a crashed RAID somewhere.

% -----------------------------------------------------------------------------
% The table of contents and list of figures and tables
% Comment out \listoffigures and \listoftables if there are no
% figures or tables. Make sure this starts on an odd numbered page
\cleardoublepage                % TOC needs to start on an odd page
\tableofcontents
\listoffigures
% \listoftables

% -----------------------------------------------------------------------------
% This is where the body of the report begins.
\SANDmain       % Start the main part of the report.

\input{Introduction.tex}

\input{Tutorial.tex}

\input{BasicUsage.tex}

\input{CustomizingCompositing.tex}

\input{Strategies.tex}

\input{Communicators.tex}

\input{Transitioning.tex}


\chapter{Future Work}

The majority of the development for \IceT was finished by 2004.  Since
then, \IceT has proven to be a stable and versatile library that is
currently being used in several production applications.

The following is a list of potential changes to \IceT.  As of this writing,
none of these are currently under development.  Rather, these are
identified shortcomings of various degrees in \IceT.  These features will
be handled on an as needed basis, assuming the need should arise.

\begin{description}
\item[Update scalability tests.] The scalability tests for \IceT were run
  during its major development, which was several years ago.  At the time,
  64 nodes was considered a pretty enormous big visualization cluster.
  Nowadays, \IceT is sometimes used to run visualization on supercomputers
  containing thousands of processes.  Verifying the scalability of the
  system occasionally is always a good idea.  Also, the
  \index{strategy!reduce}reduce strategy makes assumptions about the
  relative performance of the binary tree and binary swap composition
  algorithms.  The performance point might have changed.  Also, given that
  binary swap is reducing the image with each step, it might be worthwhile
  to switch to binary tree in the middle of the binary swap algorithm.
\item[Render aborts.] In interactive applications, it is often convenient
  to be able to abort a render that takes some time to finish.  Aborting a
  render in the middle of a composite is tricky, because you need to make
  sure that everyone is aware of the abort and that all communication is
  correctly canceled.  This could be partially implemented in \IceT's
  communication layer, but all the strategies still have to be ready to
  quit once a communication is canceled due to an abort (or at the very
  least ignore it without crashing).
\end{description}

% -----------------------------------------------------------------------------
% This chapter contains all of the man pages.
\chapter{Man Pages}
\label{chap:Man_Pages}

In this chapter you will find a man page for each of the functions
available in the \IceT API.

\renewcommand{\headrulewidth}{0.5pt}

\input{manpages/manpages.tex}

% -----------------------------------------------------------------------------
% Here is where the index goes.
%
\clearpage
\lhead[]{}
\rhead[]{}
\phantomsection
\addcontentsline{toc}{chapter}{Index}
\printindex

% The first printing.
\begin{SANDdistribution}[NM]
  % External addresses first
  \SANDdistExternal{3}{Berk Geveci\\ Kitware, Inc.\\ 28 Corporate Drive\\
    Clifton Park, NY 12065}
  \bigskip

   % Internal addresses next
  \SANDdistInternal{8}{1323}{Kenneth Moreland}{1424}
\end{SANDdistribution}

\end{document}
