% -*- latex -*-


\setDate{February 13, 2008}
% The following must all be on one line for latex2man to work.
\begin{Name}{3}{icetStrategy}{Kenneth Moreland}{\IceT Reference}{\CFunc{icetStrategy} -- set the strategy used to composite images.}

  \mansection{Synopsis}

  \textC{\#include <GL/ice-t.h>}

  \begin{Table}{3}
    \textC{void }\CFunc{icetStrategy}\textC{(}&\CType{IceTStrategy}&\CArg{strategy}\quad\textC{);}
  \end{Table}

  
  \mansection{Description}

  The \IceT API comes packaged with several algorithms for compositing
  images.  The algorithm to use is determined by selecting a
  \CArg{strategy}.  The strategy is selected with \CFunc{icetStrategy}.  A
  strategy must be selected before \CFunc{icetDrawFrame} is called.

  The \CArg{strategy} is of type \CType{IceTStrategy}.  This is an opaque
  type.  There are no conventions to create or change an
  \CType{IceTStrategy}, but there are several predefined strategies to
  select from.  They are:

  \begin{Description}[xxxxxxxx]
  \item[\CEnum{ICET\_STRATEGY\_SERIAL}] Basically applies a ``traditional''
    single tile composition (such as binary swap) to each tile in the order
    they were defined.  Because each process must take part in the
    composition of each tile regardless of whether they draw into it, this
    strategy is usually very inefficient when compositing for more than
    tile.  It is provided mostly for comparative purposes.
  \item[\CEnum{ICET\_STRATEGY\_DIRECT}] As each process renders an image
    for a tile, that image is sent directly to the process that will
    display that tile.  This usually results in a few processes receiving
    and processing the majority of the data, and is therefore usually an
    inefficient strategy.
  \item[\CEnum{ICET\_STRATEGY\_SPLIT}] Like \CEnum{ICET\_STRATEGY\_DIRECT},
    except that the tiles are split up, and each process is assigned a
    piece of a tile in such a way that each process receives and handles
    about the same amount of data.  This strategy is often very efficient,
    but due to the large amount of messages passed, it has not proven to be
    very scalable or robust.
  \item[\CEnum{ICET\_STRATEGY\_REDUCE}] A two phase algorithm.  In the
    first phase, tile images are redistributed such that each process has
    one image for one tile.  In the second phase, a ``traditional'' single
    tile composition is performed for each tile.  Since each process
    contains an image for only one tile, all these compositions may happen
    simultaneously.  This is a well rounded strategy that seems to perform
    well in a wide variety of applications.
  \item[\CEnum{ICET\_STRATEGY\_VTREE}] An extension to the binary tree
    algorithm for image composition.  Sets up a `virtual' composition tree
    for each tile image.  Processes that belong to multiple trees (because
    they render to more than one tile) are allowed to float between trees.
    This strategy is not quite as well load balanced as
    \CEnum{ICET\_STRATEGY\_REDUCE} or \CEnum{ICET\_STRATEGY\_SPLIT}, but
    has very well behaved network communication.
  \end{Description}

  Not all of the strategies support ordered image composition.
  \CEnum{ICET\_STRATEGY\_SERIAL}, \CEnum{ICET\_STRATEGY\_DIRECT}, and
  \CEnum{ICET\_STRATEGY\_REDUCE} do support ordered image composition.
  \CEnum{ICET\_STRATEGY\_SPLIT} and \CEnum{ICET\_STRATEGY\_VTREE} do not
  support ordered image composition and will ignore
  \CEnum{ICET\_ORDERED\_COMPOSITE} if it is enabled.


  \mansection{Errors}

  None.


  \mansection{Warnings}

  None.


  \mansection{Bugs}

  Use the \CEnum{ICET\_STRATEGY\_SPLIT} strategy with care.  It has proven
  to be unreliable on several high-speed interconnects.  Avoid using it at
  all in a production application.


  \mansection{Copyright}
  Copyright \copyright 2003 Sandia Corporation

  Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive
  license for use of this work by or on behalf of the U.S. Government.
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that this Notice and any statement
  of authorship are reproduced on all copies.


  \mansection{See Also}

  \CFuncSeeAlso{icetDrawFrame}, \CFuncSeeAlso{icetGetStrategyName}

\end{Name}


% These are emacs settings that go at the end of the file.
% Local Variables:
% writestamp-format: "%B %e, %Y"
% writestamp-prefix: "^\\\\setDate{"
% writestamp-suffix: "}$"
% End:
