% -*- latex -*-


\setDate{September 20, 2010}
% The following must all be on one line for latex2man to work.
\begin{Name}{3}{icetGet}{Kenneth Moreland}{\IceT Reference}{\CFunc{icetGet} -- get an \IceT state parameter}

  \mansection{Synopsis}

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

  \begin{Table}{3}
    \textC{void }\icetGetDoublev\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTDouble *}&\CArg{params}\quad\textC{);}
  \end{Table}

  \begin{Table}{3}
    \textC{void }\icetGetFloatv\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTFloat *}&\CArg{params}\quad\textC{);}
  \end{Table}

  \begin{Table}{3}
    \textC{void }\icetGetIntegerv\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTInt *}&\CArg{params}\quad\textC{);}
  \end{Table}

  \begin{Table}{3}
    \textC{void }\icetGetBooleanv\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTBoolean *}&\CArg{params}\quad\textC{);}
  \end{Table}

  \begin{Table}{3}
    \textC{void }\icetGetEnumv\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTEnum *}&\CArg{params}\quad\textC{);}
  \end{Table}

  \begin{Table}{3}
    \textC{void }\icetGetBitFieldv\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTBitField *}&\CArg{params}\quad\textC{);}
  \end{Table}

  \begin{Table}{3}
    \textC{void }\icetGetPointerv\textC{(}&\textC{IceTEnum}&\CArg{pname}\textC{,} \\
      &\textC{IceTVoid **}&\CArg{params}\quad\textC{);}
  \end{Table}

  
  \mansection{Description}

  Like \OpenGL, the operation of \IceT is defined by a large state machine.
  Also like \OpenGL, the state parameters can be retrieved through the
  \CFunc{icetGet} functions.  Each function takes a symbolic constant,
  \CArg{pname}, which identifies the state parameter to retrieve.  They
  also each take an array, \CArg{params}, which will be filled with the
  values in \CArg{pname}.  It is the calling application's responsibility
  to ensure that \CArg{params} is big enough to hold all the data.


  \mansection{State Parameters}

  The following list identifies valid values for \CArg{pname} and a
  description of the associated state parameter.

  \begin{Description}[xxxxxxxx]
  \item[\CEnum{ICET\_BACKGROUND\_COLOR}] The color that \IceT is currently
    assuming is the background color.  It is an RGBA value that is stored
    as four floating point values.  This value is set either to the last
    value passed to \CFunc{icetDrawFrame}, the \OpenGL background color if
    \CFunc{icetGLDrawFrame} was called, or to black for color blending.
    (The correct background color is restored later.)
  \item[\CEnum{ICET\_BACKGROUND\_COLOR\_WORD}] The same as
    \CEnum{ICET\_BACKGROUND\_COLOR} except that each component is stored as
    8-bit RGBA values and packed in a 4-byte integer.  The idea is to
    rapidly fill the background of color buffers.
  \item[\CEnum{ICET\_BLEND\_TIME}] The total time, in seconds, spent in
    performing color blending of images during the last call to
    \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.  Stored as a double.
    An alias for this value is \CEnum{ICET\_COMPARE\_TIME}.
  \item[\CEnum{ICET\_BUFFER\_READ\_TIME}] The total time, in seconds, spent
    copying buffer data and reading from \OpenGL buffers during the last
    call to \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.  Stored as a
    double.
  \item[\CEnum{ICET\_BUFFER\_WRITE\_TIME}] The total time, in seconds,
    spent writing to \OpenGL buffers during the last call to
    \CFunc{icetGLDrawFrame}.  Always set to 0.0 after a call to
    \CFunc{icetDrawFrame}.  Stored as a double.
  \item[\CEnum{ICET\_BYTES\_SENT}] The total number of bytes sent by the
    calling process for transferring image data during the last call to
    \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.  Stored as an integer.
  \item[\CEnum{ICET\_COLOR\_FORMAT}] The color format of images to be
    created by the rendering subsystem and composited by \IceT.  Use
    \CFunc{icetSetColorFormat} to set the color format.  Use
    \CFunc{icetImageGetColorFormat} to safely get the color format for a
    particular image.
  \item[\CEnum{ICET\_COMPARE\_TIME}] The total time, in seconds, spent in
    performing Z comparisons of images during the last call to
    \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.  Stored as a double.
    An alias for this value is \CEnum{ICET\_BLEND\_TIME}.
  \item[\CEnum{ICET\_COMPOSITE\_MODE}] The composite mode set by
    \CFunc{icetCompositeMode}.  A single entry stored as an
    \textC{IceTEnum}.
  \item[\CEnum{ICET\_COMPOSITE\_ORDER}] The order in which images are to be
    composited if \CEnum{ICET\_ORDERED\_COMPOSITE} is enabled and the
    current strategy supports ordered compositing.  The parameter contains
    \CEnum{ICET\_NUM\_PROCESSES} entries.  The value of this parameter is
    set with \CFunc{icetCompositeOrder}.  If the element of index $i$ in
    the array is set to $j$, then there are $i$ images ``on top'' of the
    image generated by process $j$.
  \item[\CEnum{ICET\_COMPOSITE\_TIME}] The total time, in seconds, spent in
    compositing during the last call to \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame}.  Equal to $\CEnum{ICET\_TOTAL\_DRAW\_TIME} -
    \CEnum{ICET\_RENDER\_TIME} - \CEnum{ICET\_BUFFER\_READ\_TIME} -
    \CEnum{ICET\_BUFFER\_WRITE\_TIME}$.  Stored as a double.
  \item[\CEnum{ICET\_COMPRESS\_TIME}] The total time, in seconds, spent in
    compressing image data using active pixel encoding during the last call
    to \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.  Stored as a double.
  \item[\CEnum{ICET\_DATA\_REPLICATION\_GROUP}] An array of process ids.
    There are \CEnum{ICET\_DATA\_REPLICATION\_GROUP\_SIZE} entries in the
    array.  \IceT assumes that all processes in the list will create the
    exact same image with their draw functions (set with
    \CFunc{icetDrawCallback} or \CFunc{icetGLDrawCallback}).  The local
    process id (\CEnum{ICET\_RANK}) will be part of this list.
  \item[\CEnum{ICET\_DATA\_REPLICATION\_GROUP\_SIZE}] The length of the
    \CEnum{ICET\_DATA\_REPLICATION\_GROUP} array.
  \item[\CEnum{ICET\_DEPTH\_FORMAT}] The depth format of images to be
    created by the rendering subsystem and composited by \IceT.  Use
    \CFunc{icetSetDepthFormat} to set the depth format.  Use
    \CFunc{icetImageGetDepthFormat} to safely get the depth format for a
    particular image.
  \item[\CEnum{ICET\_DIAGNOSTIC\_LEVEL}] The diagnostics flags set with
    \CFunc{icetDiagnostics}.
  \item[\CEnum{ICET\_DISPLAY\_NODES}] An array of process ranks.  The size
    of the array is equal to the number of tiles
    (\CEnum{ICET\_NUM\_TILES}).  The $i^{\mathrm{th}}$ entry is the rank of
    the process that is displaying the tile described by the
    $i^{\mathrm{th}}$ entry in \CEnum{ICET\_TILE\_VIEWPORTS}.
  \item[\CEnum{ICET\_DRAW\_FUNCTION}] A pointer to the drawing callback
    function, as set by \CFunc{icetDrawCallback}.
  \item[\CEnum{ICET\_FRAME\_COUNT}] The number of times
    \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame} has been called for
    the current context.
  \item[\CEnum{ICET\_GEOMETRY\_BOUNDS}] An array of vertices whose convex
    hull bounds the drawn geometry.  Set with \CFunc{icetBoundingVertices}
    or \CFunc{icetBoundingBox}.  Each vertex has three coordinates and are
    tightly packed in the array.  The size of the array is $3 \times
    \CEnum{ICET\_NUM\_BOUNDING\_VERTS}$.
  \item[\CEnum{ICET\_GLOBAL\_VIEWPORT}] Defines a viewport in an infinite
    logical display that covers all tile viewports (listed in
    \CEnum{ICET\_TILE\_VIEWPORTS}).  The viewport, like an \OpenGL viewport,
    is given as the integer four-tuple $\langle x, y, width, height
    \rangle$.  $x$ and $y$ are placed at the leftmost and lowest position
    of all the tiles, and $width$ and $height$ are just big enough for the
    viewport to cover all tiles.
  \item[\CEnum{ICET\_NUM\_BOUNDING\_VERTS}] The number of bounding vertices
    listed in the \CEnum{ICET\_GEOMETRY\_BOUNDS} parameter.
  \item[\CEnum{ICET\_NUM\_TILES}] The number of tiles in the defined
    display.  Basically equal to the number of times \CFunc{icetAddTile}
    was called after the last \CFunc{icetResetTiles}.
  \item[\CEnum{ICET\_NUM\_PROCESSES}] The number of processes in the
    parallel job as given by the \CType{IceTCommunicator} object associated
    with the current context.
  \item[\CEnum{ICET\_PHYSICAL\_RENDER\_HEIGHT}] The height of the images
    generated by the rendering system.  This is set to the \OpenGL viewport
    height by \CFunc{icetGLDrawFrame} or otherwise by explicitly setting it
    with \CFunc{icetPhysicalRenderSize} or otherwise implicitly to the
    largest tile height specified with \CFunc{icetAddTile}.
  \item[\CEnum{ICET\_PHYSICAL\_RENDER\_WIDTH}] The width of the images
    generated by the rendering system.  This is set to the \OpenGL viewport
    width by \CFunc{icetGLDrawFrame} or otherwise by explicitly setting it
    with \CFunc{icetPhysicalRenderSize} or otherwise implicitly to the
    largest tile width specified with \CFunc{icetAddTile}.
  \item[\CEnum{ICET\_PROCESS\_ORDERS}] Basically, the inverse of
    \CEnum{ICET\_COMPOSITE\_ORDER}.  The parameter contains
    \CEnum{ICET\_NUM\_PROCESSES} entries.  If the element of index $i$ in
    the array is set to $j$, then there are $j$ images ``on top'' of the
    image generated by process $i$.
  \item[\CEnum{ICET\_RANK}] The rank of the process as given by the
    \CType{IceTCommunicator} object associated with the current context.
  \item[\CEnum{ICET\_RENDER\_TIME}] The total time, in seconds, spent in
    the drawing callback during the last call to \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame}.  Stored as a double.
  \item[\CEnum{ICET\_SINGLE\_IMAGE\_STRATEGY}] The single image
    sub-strategy set with \CFunc{icetSingleImageStrategy}.  Use
    \CFunc{icetGetSingleImageStrategyName} to get a user-readable name for
    the single image strategy.
  \item[\CEnum{ICET\_STRATEGY}] The strategy set with
    \CFunc{icetStrategy}.  Use \CFunc{icetGetStrategyName} to get a
    user-readable name for the strategy.
  \item[\CEnum{ICET\_STRATEGY\_SUPPORTS\_ORDERING}] Is true if and only if
    the current strategy supports ordered compositing.
  \item[\CEnum{ICET\_TILE\_DISPLAYED}] The index of the tile the local
    process is displaying.  The index will correspond to the tile entry in
    the \CEnum{ICET\_DISPLAY\_NODES} and \CEnum{ICET\_TILE\_VIEWPORTS}
    arrays.  If set to $0 <= i < \CEnum{ICET\_NUM\_PROCESSES}$, then the
    $i^{\mathrm{th}}$ entry of \CEnum{ICET\_DISPLAY\_NODES} is equal to
    \CEnum{ICET\_RANK}.  If the local process is not displaying any tile,
    then \CEnum{ICET\_TILE\_DISPLAYED} is set to $-1$.
  \item[\CEnum{ICET\_TILE\_MAX\_HEIGHT}] The maximum $height$ of any tile.
  \item[\CEnum{ICET\_TILE\_MAX\_WIDTH}] The maximum $width$ of any tile.
  \item[\CEnum{ICET\_TILE\_VIEWPORTS}] A list of viewports in the logical
    global display defining the tiles.  Each viewport is the four-tuple
    $\langle x, y, width, height \rangle$ defining the position and
    dimensions of a tile in pixels, much like a viewport is defined in
    \OpenGL.  The size of the array is $4 * \CEnum{ICET\_NUM\_TILES}$.  The
    viewports are listed in the same order as the tiles were defined with
    \CFunc{icetAddTile}.
  \item[\CEnum{ICET\_TOTAL\_DRAW\_TIME}] Time spent in the last call to
    \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.  Stored as a double.
  \end{Description}

  In addition, if you are using the \OpenGL layer (i.e., have called
  \CFunc{icetGLInitialize}), these variables, defined in \textC{IceTGL.h},
  are also available.

  \begin{Description}[xxxxxxxx]
  \item[\CEnum{ICET\_GL\_DRAW\_FUNCTION}] A pointer to the \OpenGL drawing
    callback function, as set by \CFunc{icetGLDrawCallback}.
  \item[\CEnum{ICET\_GL\_READ\_BUFFER}] The \OpenGL buffer to read from
    (and write to).  Set with \CFunc{icetGLSetReadBuffer}.
  \end{Description}


  \mansection{Errors}

  \begin{Description}[ICET\_INVALID\_OPERATION]
  \item[\CErrorEnum{ICET\_BAD\_CAST}] The state parameter requested is of a
    type that cannot be cast to the output type.
  \item[\CErrorEnum{ICET\_INVALID\_ENUM}] \CArg{pname} is not a valid state
    parameter.
  \end{Description}


  \mansection{Warnings}

  None.


  \mansection{Bugs}

  None known.


  \mansection{Notes}

  Not every state variable is documented here.  There is a set of
  parameters used internally by \IceT or are more appropriately retrieved
  with other functions such as \CFunc{icetIsEnabled}.


  \mansection{Copyright}
  Copyright \copyright 2003 Sandia Corporation

  @copyright@

  \mansection{See Also}

  \CFuncSeeAlso{icetIsEnabled}, \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:
