% -*- latex -*-

%\documentclass[pdf,ps2pdf,12pt,report,strict]{SANDreport}
\documentclass[12pt,report,strict]{SANDreport}
\usepackage{pslatex}
\usepackage[fancyhdr]{latex2man}
\usepackage{ifthen}
\usepackage{xspace}
\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@}
\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{SAND2009-3170}
\SANDprintDate{May 2009}
\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{SAND1901-0001}{January 1901}

%-----------------------------------------------------------------------------
% 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|)}
}

% 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{\icetGetBooleanv}{\CFunc[icetGet]{icetGetBooleanv}\xspace}
\newcommand{\icetGetDoublev}{\CFunc[icetGet]{icetGetDoublev}\xspace}
\newcommand{\icetGetFloatv}{\CFunc[icetGet]{icetGetFloatv}\xspace}
\newcommand{\icetGetIntegerv}{\CFunc[icetGet]{icetGetIntegerv}\xspace}
\newcommand{\icetGetPointerv}{\CFunc[icetGet]{icetGetPointerv}\xspace}
\newcommand{\icetGetColorBuffer}{\CFunc{icetGetColorBuffer}\xspace}
\newcommand{\icetGetDepthBuffer}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetGetColorBuffer}}%
    {\CFunc[icetGetColorBuffer]{icetGetDepthBuffer}}%
    {\CFunc{icetGetDepthBuffer}}%
    \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}


\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).
\item[Decouple from OpenGL.] In retrospect, tying the \IceT library so
  closely to \OpenGL was a mistake.  Although most graphical applications,
  even today, use \OpenGL for their rendering, it unnecessarily precludes
  the use of any other graphics library (such as \index{DirectX}DirectX,
  for example) or any application that does not use a graphics API to
  create images.  The direct interfacing with \OpenGL can even complicate
  the integration with applications that also use \OpenGL.  Although there
  should always be a layer to simplify the interface with \OpenGL, ideally
  you should be able to use a compositing library like \IceT independently
  of \OpenGL.
\item[Allow higher precision color buffers.]  The internal representation
  of images in \IceT uses 8-bit colors.  This was an intentional design so
  that RGBA colors can be treated as single 32-bit integers and greatly
  speed up compositing operations.  Even today, this is fine representation
  for colors.  Few display devices can provide more color resolution.
  However, when blending colors stored as 8-bit values, quantization errors
  can occur.  Most of the time this is not an issue with \IceT, but it can
  create seams in images with very low opacity.
\item[Automatically count network communication.] The way \IceT builds the
  communication metric stored in \CEnum{ICET\_BYTES\_SENT} is to require
  each strategy to count how many bytes they send.  This is a rather
  fragile implementation.  A better approach would be to have the
  communications layer count bytes.
\item[Source file names.]  The names of the internal \IceT source files are
  a bit too generic.  Names like image.c and draw.c are not clearly part of
  \IceT and might conflict with other source file names in projects where
  the libraries are used.  Although this will not cause any namespace
  collisions in linking, it can be irritating while debugging if the file
  names are not easily resolved.
\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}
