Transitioning.tex

% -*- latex -*-


\chapter{Transitioning from \IceT 1.0 to \IceT 2}
\label{chap:Transitioning}

In the transition from \IceT version 1 to \IceT version 2, one of the major
goals was to make the core \IceT library independent of \OpenGL.  All of
\IceT's abilities to interface with \OpenGL are retained but isolated in a
separate library.

This change and others necessitated changes in the \IceT interface.  This
chapter provides simple instructions for transitioning existing code to the
new \IceT interface.

\section{Header File Changes}
\label{sec:Transitioning:Header_File_Changes}

Because previous versions of \IceT were considered an \OpenGL library,
public header files were placed in a \textC{GL} subdirectory.  Previous
code included \index{ice-t.h}\index{GL/ice-t.h}\textC{GL/ice-t.h} and often
also included
\index{ice-t\_mpi.h}\index{GL/ice-t\_mpi.h}\textC{GL/ice-t\_mpi.h}.
\begin{code}
#include <GL/ice-t.h>
#include <GL/ice-t_mpi.h>
\end{code}

These header files no longer exist.  The header files are now no longer in
the \textC{GL} directory and have changed in case and spelling to
\index{IceT.h}\textC{IceT.h} and \index{IceTMPI.h}\textC{IceTMPI.h}.  There
is also a new header file called \index{IceTGL.h}\textC{IceTGL.h} that
contains the specific \OpenGL functionality.  A straight transition to
\IceT~2 will require this header file as well.
\begin{code}
#include <IceT.h>
#include <IceTGL.h>
#include <IceTMPI.h>
\end{code}

\section{Basic Type Changes}
\label{sec:Transitioning:Basic_Type_Changes}

\IceT~1 used the basic types defined by \OpenGL such as
\index{GLint}\textC{GLint} and \index{GLfloat}\textC{GLfloat}.  \IceT now
defines its own basic types such as \index{IceTInt}\textC{IceTInt} and
\index{IceTFloat}\textC{IceTFloat}, and these new types should be used in
place of the \OpenGL types with respect to data passed to and from \IceT.

\section{Function Name Changes}
\label{sec:Transitioning:Function_Name_Changes}

To make the \OpenGL layer explicit, all functions in this layer are prefixed
with \textC{icetGL}.  This along with some other minor implementation
details require slight changes in existing code.

First, before any other \textC{icetGL} functions are called,
\CFunc{icetGLInitialize} must be called.  \CFunc{icetGLInitialize} should
be called right after the context is created:
\begin{code}
icetCreateContext(comm);
icetGLInitialize();
\end{code}

Make certain to call \CFunc{icetGLInitialize} for \emph{each} context for
which you use the \OpenGL layer.

Apart from adding a function call for \CFunc{icetGLInitialize}, there are
only two function names that have changed:
\index{icetDrawFunc}\textCF{icetDrawFunc} and \CFunc{icetDrawFrame} have
changed to \CFunc{icetGLDrawCallback} and \CFunc{icetGLDrawFrame},
respectively.

Technically, a function called \CFunc{icetDrawFrame} still exists, but its
interface has changed (so you should get a compiler error if you try to use
it) and its behavior now skips any \OpenGL specific operations (specifically
reading and adjusting \OpenGL state).

The function \index{icetInputOutputBuffers}\textCF{icetInputOutputBuffers}
has also been removed.  It has been replaced with the two functions
\CFunc{icetSetColorFormat} and \CFunc{icetSetDepthFormat}, which basically
set the input buffers.  The output buffers are implicitly set to be the
same as the input buffers, but if the \CEnum{ICET\_COMPOSITE\_ONE\_BUFFER}
feature is enabled, then the depth buffer will be suppressed in the output
if both the color and depth buffer are read as input.  This is the only
sensible case for the input and output buffers to differ.

There is also a new function named \CFunc{icetCompositeMode} to explicitly
set the composite operation (z-buffer or blending).  Previous versions of
\IceT implicitly set the composite mode based on what type of image data
was available.  To ensure that \IceT is behaving as the user expects, this
is now set explicitly.  You will get errors if you have picked a composite
mode that cannot be implemented with the image data available.

\section{Getting Image Data}
\label{sec:Transitioning:Getting_Image_Data}

The \index{icetGetColorBuffer}\textCF{icetGetColorBuffer} and
\index{icetGetDepthBuffer}\textCF{icetGetDepthBuffer} functions no longer
exist.  The underlying data storage for images has become more flexible,
and this method of getting image data became insufficient.

Instead, \CFunc{icetGLDrawFrame} now returns an \CType{IceTImage} object.
There is a suite of new functions available, described in
Chapter~\ref{sec:Basic_Usage:Image_Objects}, that allow you to get data
from \CType{IceTImage} objects.  The methods that get color and data
information from image objects are \icetImageGetColorub and
\icetImageGetDepthf, respectively.

Also note that \IceT now uses floating point numbers for depth values.
Previous versions of \IceT used 32-bit integers.  Although using these
integers was fast, \IceT had problems with identifying background pixels.
Different graphics hardware used different values for the maximum depths.
However, the \OpenGL specification places the maximum depth value at $1.0$
if using floating point values.

\section{Miscellaneous Changes}
\label{sec:Transitioning:Miscellaneous}

The serial strategy has been renamed to the sequential strategy.  This
better reflects the actual operation of the strategy as image compositing
is still performed in parallel.  As such, the
\CEnum{ICET\_STRATEGY\_SERIAL} identifier has changed to
\CEnum{ICET\_STRATEGY\_SEQUENTIAL}.

\section{Libraries}
\label{sec:Transitioning:Libraries}

The names of the libraries have changed from \index{icet (library)}icet and
\index{icet\_mpi (library)}icet\_mpi to \index{IceTCore (library)}IceTCore
and \index{IceTMPI (library)}IceTMPI, respectively.  Additionally, there is
also an \index{IceTGL (library)}IceTGL library that contains code for the
\OpenGL layer.  The \index{icet\_strategies (library)}icet\_strategies
library no longer exists.  Everything in this library has been merged into
IceTCore.

\section{CMake Configuration}
\label{sec:Transitioning:CMake_Configuration}

The \index{CMake}CMake configuration for CMake has changed a bit between
CMake version 1 and 2.  You no longer need a copy of
\index{FindIceT.cmake}FindIceT.cmake.  The \textC{FIND\_PACKAGE(IceT)}
still works, but relies only on the
\index{IceTConfig.cmake}IceTConfig.cmake file generated by \IceT.

The use file prevously defined in \CEnum{ICET\_USE\_FILE} no longer exists.
Instead, you will need to insert your own commands to specify the \IceT
header and library locations.

There is a new variable called \CEnum{ICET\_GL\_LIBS} that specifies the
libraries used for the \OpenGL layer.  The variables
\CEnum{ICET\_CORE\_LIBS} and \CEnum{ICET\_MPI\_LIBS} still exist to specify
the core and MPI layer libraries, respectively.

Here is some typical CMake script fragment for using \IceT.

\begin{code}
FIND_PACKAGE(IceT REQUIRED)

INCLUDE_DIRECTORIES(${ICET_INCLUDE_DIRS})

ADD_EXECUTABLE(myprog ${SRCS})

TARGET_LINK_LIBRARIES(myproc
  ${ICET_CORE_LIBS}
  ${ICET_GL_LIBS}
  ${ICET_MPI_LIBS}
  )
\end{code}
%$