*** empty log message ***

[charm.git] / doc / libraries / liveviz.tex

\section{Introduction}

If array elements compute a small piece of a large 2D image, then these 
image chunks can be combined across processors to form one large 
image using the liveViz library. In other 
words, liveViz provides a way to reduce 2D-image data, which 
combines small chunks
 of images deposited by chares into one large image.

This visualization library follows the client server model.
The server, a parallel Charm++ program, does all image assembly, 
and opens a network (CCS) socket which clients use to request and 
download images.  The client is a small Java program.
A typical use of this is:
\begin{alltt}
        cd charm/pgms/charm++/ccs/liveViz/server
        make
        ./charmrun ./pgm +p2 ++server ++server-port 1234 &
        ~/charm/bin/liveViz localhost 1234
\end{alltt}



\section{How to use liveViz with \charmpp{} program}

The liveViz routines are in the Charm++ header ``liveViz.h''.

A typical program provides a chare array with one entry method 
with the following prototype:

\begin{alltt}
  entry void functionName(liveVizRequestMsg *m);
\end{alltt}

This entry method is supposed to deposit its (array element's) chunk of 
the image. This entry method has following structure:

\begin{alltt}
  void myArray::functionName (liveVizRequestMsg *m)
  \{
    // prepare image chunk
       ...

    liveVizDeposit (m, startX, startY, width, height, imageBuff, this);

    // delete image buffer if it was dynamically allocated
  \}
\end{alltt}

Here, ``width'' and ``height'' are the size, in pixels, of this array
element's portion of the image, contributed in ``imageBuff'' (described below).
This will show up on the client's assembled image at 0-based pixel
(startX,startY).  The client's display width and height are stored
in m->req.wid and m->req.ht.

By default liveViz combines image chunks by doing a saturating sum of 
overlapping pixel values. If you want liveViz to combine image chunks by using 
max (i.e. for overlapping pixels in deposited image chunks, final image will 
have the pixel with highest intensity or in other words largest value), you need
to pass one more parameter (liveVizCombine\_t) to the ``liveVizDeposit'' function:

\begin{alltt}
 liveVizDeposit (m, startX, startY, width, height, imageBuff, this, 
                   max\_image\_data);
\end{alltt}

You can also reduce floating-point image data using
 sum\_float\_image\_data or max\_float\_image\_data.


\section{Format of deposit image}

``imageBuff'' is run of bytes representing a rectangular portion
of the image.  This buffer represents image using a row-major format,
so 0-based pixel (x,y) (x increasing to the right, y increasing downward
in typical graphics fashion) is stored at array offset ``x+y*width''.

If the image is gray-scale (as determined by liveVizConfig, below), each pixel
is represented by one byte.  If the image is color, each pixel is represented
by 3 consecutive bytes representing red, green, and blue intensity.

If the image is floating-point, each pixel is represented by a single
`float', and after assembly colorized by calling the user-provided
routine below.  This routine converts fully assembled `float' pixels 
to RGB 3-byte pixels, and is called only on processor 0 after each
client request.

\begin{alltt}
extern "C"
void liveVizFloatToRGB(liveVizRequest &req, 
        const float *floatSrc, unsigned char *destRgb,
        int nPixels);
\end{alltt}


\section{liveViz Initialization}

liveViz library needs to be initialized before it can be used for 
visualization. For initialization follow the following steps
from your main chare:

\begin{enumerate}
\item Create your chare array (array proxy object 'a') with the entry 
      method 'functionName' (described above).
\item Create a CkCallback object ('c'), specifying 'functionName' as the 
      callback function.  This callback will be invoked whenever the
      client requests a new image.
\item Create a liveVizConfig object ('cfg').  LiveVizConfig takes a number
     of parameters, as described below.
\item Call liveVizInit (cfg, a, c).
\end{enumerate}

The liveVizConfig parameters are:
\begin{itemize}
  \item The first parameter is the pixel type to be reduced:
     \begin{itemize}
       \item ``false'' or liveVizConfig::pix\_greyscale means a greyscale image (1 byte per pixel).
       \item ``true'' or liveVizConfig::pix\_color means a color image (3 RGB bytes per pixel).
       \item liveVizConfig::pix\_float means a floating-point color image (1 float per pixel, can only be used with sum\_float\_image\_data or max\_float\_image\_data).
     \end{itemize}
   \item The second parameter is the flag ``serverPush'', which is passed to the client application. If set to true, the client will repeatedly request for images. When set to false the client will only request for images when its window is resized and needs to be updated.     
   \item The third parameter is an optional 3D bounding box (type CkBbox3d).  If present, this puts the client into a 3D visualization mode.
\end{itemize}

A typical 2D, RGB, non-push call to liveVizConfig looks like this:
\begin{alltt}
   liveVizConfig cfg(true,false);
\end{alltt}

\section{Compilation}

A \charmpp{} program that uses liveViz must be linked with '-module liveViz'. 

Before compiling a liveViz program, the liveViz library may need to be compiled. 
To compile the liveViz library:
\begin{itemize}
\item go to .../charm/tmp/libs/ck-libs/liveViz
\item make
\end{itemize}


\section{Poll Mode}

In some cases you may want a server to deposit images only when it is ready to do so. 
For this case the server will not register a callback function that triggers image generation, but rather the server will deposit an image at its convenience.
For example a server may want to create a movie or series of images corresponding to some
timesteps in a simulation. The server will have a timestep loop in which an array computes 
some data for a timestep. At the end of each iteration the server will deposit the image. The use of LiveViz's Poll Mode supports this type of server generation of images.

Poll Mode contains a few significant differences to the standard mode. First we describe the use of Poll Mode, and then we will describe the differences. liveVizPoll must get control during the creation of your array,
so you call liveVizPollInit with no parameters.

\begin{alltt}
        liveVizPollInit();
        CkArrayOptions opts(nChares);
        arr = CProxy_lvServer::ckNew(opts);
\end{alltt}

To deposit an image, the server just calls liveVizPollDeposit. The server must take care not to generate too many images, before a client requests them. Each server generated image is buffered until the client can get the image. The buffered images will be stored in memory on processor 0.

\begin{alltt}
  liveVizPollDeposit( this,
                      startX,startY,            // Location of local piece
                      localSizeX,localSizeY,    // Dimensions of the piece I'm depositing
                      globalSizeX,globalSizeY,  // Dimensions of the entire image
                      img,                      // Image byte array
                      sum_image_data,           // Desired image combiner
                      3                         // Bytes/pixel
                    );
\end{alltt}
The last two parameters are optional. By default they are set to sum\_image\_data and 3 bytes per pixel.



A sample liveVizPoll server and client are available at:
\begin{alltt}
           .../charm/examples/charm++/lvServer
           .../charm/java/bin/lvClient
\end{alltt}
This example server uses a PythonCCS command to cause an image to be generated by the server. The client also then gets the image.

LiveViz provides multiple image combiner types. Any supported type can be used as a parameter to liveVizPollDeposit. Valid combiners include: sum\_float\_image\_data, max\_float\_image\_data, sum\_image\_data, and max\_image\_data. 

The differences in Poll Mode may be apparent. There is no callback function which causes the server to generate and deposit an image. Furthermore, a server may generate an image before or after a client has sent a request. The deposit function, therefore is more complicated, as the server will specify information about the image that it is generating. The client will no longer specify the desired size or other configuration options, since the server may generate the image before the client request is available to the server. The liveVizPollInit call takes no parameters.

The server should call Deposit with the same global size and combiner type on all of the array elements which correspond to the ``this'' parameter.

The latest version of liveVizPoll is not backwards compatable with older versions. The old version had some fundamental problems which would occur if a server generated an image before a client requested it. Thus the new version buffers server generated images until requested by a client. Furthermore the client requests are also buffered if they arrive before the server generates the images. Problems could also occur during migration with the old version.