% -*- latex -*-


\setDate{August  9, 2010}
% The following must all be on one line for latex2man to work.
\begin{Name}{3}{icetDrawFrame}{Kenneth Moreland}{\IceT Reference}{\CFunc{icetDrawFrame} -- renders and composites a frame}

  \mansection{Synopsis}

  \textC{\#include <IceT.h>}

  \begin{Table}{3}
    \CType{IceTImage}\textC{ }\CFunc{icetDrawFrame}\textC{(}
    &\textC{const IceTDouble *}&\CArg{projection\_matrix}\textC{,} \\
    &\textC{const IceTDouble *}&\CArg{modelview\_matrix}\textC{,} \\
    &\textC{const IceTFloat *}&\CArg{background\_color}\quad\textC{);}
  \end{Table}

  
  \mansection{Description}

  Initiates a frame draw using the given transformation matrices (modelview
  and projection).  If you are using \OpenGL, you should probably use the
  \CFunc{icetGLDrawFrame} function and associated
  \CFunc{icetGLDrawCallback}.

  Before \IceT may render an image, the tiled display needs to be defined
  (using \CFunc{icetAddTile}), the drawing function needs to be set (using
  \CFunc{icetDrawCallback}), and composite strategy must be set (using
  \CFunc{icetStrategy}).  The single image sub-strategy may also optionally
  be set (using \CFunc{icetSingleImageStrategy}).

  All processes in the current \IceT context must call
  \CFunc{icetDrawFrame} for it to complete.

  During compositing, \IceT uses the given \CArg{projection\_matrix} and
  \CArg{modelview\_matrix}, as well as the bounds given in the last call to
  \CFunc{icetBoundingBox} or \CFunc{icetBoundingVertices}, to determine
  onto which pixels the local geometry projects.  If the given matrices are
  not the same used in the rendering or the given bounds do not contain the
  geometry, \IceT may clip the geometry in surprising ways.  Furthermore,
  \IceT will modify the \CArg{projection\_matrix} for the drawing callback
  to change the projection onto (or in between) tiles.  Thus, you should
  pass the desired \CArg{projection\_matrix} to \CFunc{icetDrawFrame} and
  then use the version passed to the drawing callback.


  \mansection{Return Value}

  On each \index{display~process}display process (as defined by
  \CFunc{icetAddTile}, \CFunc{icetDrawFrame} returns an image of the fully
  composited image.  The contents of the image are undefined for any
  non-display process.

  If the \CEnum{ICET\_COMPOSITE\_ONE\_BUFFER} option is on and both a color
  and depth buffer is specified with \icetSetColorFormat and
  \icetSetDepthFormat, then the returned image might be missing the depth
  buffer.  The rational behind this option is that often both the color and
  depth buffer is necessary in order to composite the color buffer, but the
  composited depth buffer is not needed.  In this case, the compositing
  might save some time by not transferring depth information at the latter
  stage of compositing.

  The returned image uses memory buffers that will be reclaimed the next
  time \IceT renders a frame.  Do not use this image after the next call to
  \CFunc{icetDrawFrame} (unless you have changed the \IceT context).


  \mansection{Errors}

  \begin{Description}[ICET\_INVALID\_OPERATION]
  \item[\CErrorEnum{ICET\_INVALID\_OPERATION}]
    Raised if the \CFunc{icetGLInitialize} has not been called or if the
    drawing callback has not been set.  Also can be raised if
    \CFunc{icetDrawFrame} is called recursively, probably from within the
    drawing callback.
  \item[\CErrorEnum{ICET\_OUT\_OF\_MEMORY}]
    Not enough memory left to hold intermittent frame buffers and other
    temporary data.
  \end{Description}

  \CFunc{icetDrawFrame} may also indirectly raise an error if there is an
  issue with the strategy or callback.


  \mansection{Warnings}

  None.


  \mansection{Bugs}

  If compositing with color blending on, the image returned may have a
  black background instead of the \CArg{background\_color} requested.  This
  can be corrected by blending the returned image over the desired
  background.  This will be done for you if the
  \CEnum{ICET\_CORRECT\_COLORED\_BACKGROUND} is on.


  \mansection{Copyright}
  Copyright \copyright 2003 Sandia Corporation

  @copyright@

  \mansection{See Also}

  \CFuncSeeAlso{icetAddTile},
  \CFuncSeeAlso{icetBoundingBox},
  \CFuncSeeAlso{icetBoundingVertices},
  \CFuncSeeAlso{icetDrawCallback},
  \CFuncSeeAlso{icetGLDrawFrame},
  \CFuncSeeAlso{icetSingleImageStrategy},
  \CFuncSeeAlso{icetStrategy}

\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:
