% -*- latex -*-


\setDate{February 14, 2008}
% The following must all be on one line for latex2man to work.
\begin{Name}{3}{icetGetColorBuffer}{Kenneth Moreland}{\IceT Reference}{\icetGetColorBuffer, \icetGetDepthBuffer -- retrieves the last computed color or depth buffer.}

  \label{manpage:icetGetDepthBuffer}
  \index{icetGetDepthBuffer|(textbf}

  \mansection{Synopsis}

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

  \begin{Table}{4}
    \textC{GLubyte}&\textC{*}\icetGetColorBuffer&\textC{(}&\textC{void}\quad\textC{)}; \\
    \textC{GLuint}&\textC{*}\icetGetDepthBuffer&\textC{(}&\textC{void}\quad\textC{)}; \\
  \end{Table}

  
  \mansection{Description}

  Returns a buffer containing the result of the image composition performed
  by the last call to \CFunc{icetDrawFrame}.  Be aware that a color or
  depth buffer may not have been computed with the last call to
  \CFunc{icetDrawFrame}.  \IceT avoids the computation and network
  transfers for any unnecessary buffers unless specifically requested
  otherwise with the flags given to the \CFunc{icetInputOutputBuffers}
  function.  Use a call to \icetGetBooleanv with a value of
  \CEnum{ICET\_COLOR\_BUFFER\_VALID} or \CEnum{ICET\_DEPTH\_BUFFER\_VALID}
  to determine whether either of these buffers are available.  Attempting
  to get a nonexistent buffer will result with a warning being emitted and
  \textC{NULL} returned.


  \mansection{Return Value}

  \icetGetColorBuffer returns the color buffer for the displayed tile.
  Each pixel value can be assumed to be four consecutive bytes in the
  buffer.  The pixels are also always aligned on 4-byte boundaries.  The
  format of the color buffer is defined by the state parameter
  \CEnum{ICET\_COLOR\_FORMAT}, which is typically either \CEnum{GL\_RGBA},
  \CEnum{GL\_BGRA}, or \CEnum{GL\_BGRA\_EXT}.

  \icetGetDepthBuffer returns the depth buffer for the displayed tile.
  Depth values are stored as 32-bit integers.

  The width and the height of the buffer are determined by the width and
  the height of the displayed tile at the time \CFunc{icetDrawFrame} was
  called.  If the tile layout is changed since the last call to
  \CFunc{icetDrawFrame}, the dimensions of the buffer returned may not
  agree with the dimensions stored in the current \IceT state.

  The memory returned by \icetGetColorBuffer and \icetGetDepthBuffer need
  not, and should not, be freed.  It will be reclaimed in the next call to
  \CFunc{icetDrawFrame}.  Expect the data returned to be obliterated on the
  next call to \CFunc{icetDrawFrame}.


  \mansection{Errors}

  None.


  \mansection{Warnings}

  \begin{Description}[ICET\_INVALID\_OPERATION]
  \item[\CErrorEnum{ICET\_INVALID\_VALUE}] The appropriate buffer is not
    available, either because it was not computed or it has been
    obliterated by a subsequent \IceT computation.
  \end{Description}


  \mansection{Bugs}

  The returned image may have a value of $(R, G, B, A) = (0, 0, 0, 0)$ for
  a pixel instead of the true background color.  This can usually be
  corrected by replacing all pixels with an alpha value of $0$ with the
  background color.

  The buffers are stored in a shared memory pool attached to a particular
  context.  As such, the buffers are not copied with the state.  Also,
  because they are shared, it is conceivable that the buffers will be
  reclaimed before the next call to \CFunc{icetDrawFrame}.  If this should
  happen, the \CEnum{ICET\_COLOR\_BUFFER\_VALID} and
  \CEnum{ICET\_DEPTH\_BUFFER\_VALID} state variables will be set
  accordingly.


  \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{icetInputOutputBuffers},
  \CFuncSeeAlso{icetGet}

  \index{icetGetDepthBuffer|)textbf}
\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:
