IceTUsersGuide.tex

% -*- 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{pdfborder={0 0 0}}
\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{SAND2011-5011}
\SANDprintDate{August 2011}
\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}
\SANDsupersed{SAND2010-7451}{January 2011}

%-----------------------------------------------------------------------------
% 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{\icetImageGetColorcub}{\CFunc[icetImageGetColor]{icetImageGetColorcub}\xspace}
\newcommand{\icetImageGetColorcui}{\CFunc[icetImageGetColor]{icetImageGetColorcui}\xspace}
\newcommand{\icetImageGetColorcf}{\CFunc[icetImageGetColor]{icetImageGetColorcf}\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{\icetImageGetDepthcf}{%
  \ifthenelse%
    {\equal{\currentmansection}{icetImageGetColor}}%
    {\CFunc[icetImageGetColor]{icetImageGetDepthcf}}%
    {\CFunc[icetImageGetDepth]{icetImageGetDepthcf}}%
    \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%
}

% Avoid putting figures on their own page.
\renewcommand{\textfraction}{0.05}
\renewcommand{\topfraction}{0.95}

% Make sure this is big enough so that only big figures end up on their own
% page but small enough so that if a figure does have to be on its own
% page, it won't push everything to the bottom because it's not big enough
% to have its own page.
\renewcommand{\floatpagefraction}{.75}

%-----------------------------------------------------------------------------
% 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{NewStrategies.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.  In 2011 several
scalability tests were run and the compositing algorithms updated to better
support petascale computing.

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[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[Multithreaded compositing] \IceT is specifically designed for
  distributed memory parallel computing.  It is clear that current and
  future high-performance computers are built with nodes comprising many
  computing cores each.  It may be necessary to increase the thread safety
  of \IceT and implement hybrid distributed-shared memory parallel
  compositing algorithms.
\item[Memory conservation] \IceT's compositing algorithms require multiple
  image buffers.  To save allocation time and prevent memory fragmenting,
  \IceT keeps image buffers around in its own memory pool.
  Memory-constrained applications may prefer that \IceT releases this memory
  between frames and take the performance hit.  \IceT's compositing
  algorithms could also stand a pass at minimizing the memory they use.
\item[Multi-tile vs. big image compositing] \IceT contains several special
  algorithms for compositing multi-tile images.  However, these strategies
  have never been properly compared to the compositing of a single very
  large image.  This comparison should be done, and if the single
  compositing is faster then perhaps make a new strategy to combine tiles
  to a single large image before compositing, then split back up at the
  end.
\item[Matrix functions] \IceT contains several convenience functions for
  $4 \times 4$ matrix transformations (described in
  Chapter~\ref{sec:New_Strategies:Matrix_Operations} starting on
  page~\pageref{sec:New_Strategies:Matrix_Operations}).  They are hidden
  under the assumption that programs using \IceT will have similar
  functionality from its own rendering system, but perhaps that is not
  always the case.  Should these functions be exposed?
\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.
%
\begin{flushleft}
  \clearpage
  \lhead[]{}
  \rhead[]{}
  \phantomsection
  \addcontentsline{toc}{chapter}{Index}
  \printindex
\end{flushleft}

% The first printing.
\begin{SANDdistribution}[NM]
  % External addresses first
  \SANDdistExternal{1}{Berk Geveci\\ Kitware, Inc.\\ 28 Corporate Drive\\
    Clifton Park, NY 12065}
  \SANDdistExternal{1}{Wesley Kendall\\ 1208 Lula Bell Dr\\
    Powell, TN 37849}
  \SANDdistExternal{1}{Hank Childs\\ Lawrence Berkeley National Lab\\
    1 Cyclotron Road, Mailstop 50F1614\\ Berkeley, CA 94720-8139}
  \bigskip

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

\end{document}