% -*- latex -*-


\setDate{July 11, 2011}
% 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\_COLLECT\_TIME}] The total time spent in collecting
    image fragments to display processes during the last call to
    \CFunc{icetDrawFrame} or \CFunc{icetGLDrawFrame}.
  \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\_MAGIC\_K}] The target $k$ value used when compositing
    with the radix-k single image strategy.
  \item[\CEnum{ICET\_MAX\_IMAGE\_SPLIT}] The target number of maximum image
    splits to be performed by compositing strategies.
  \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}.  This includes all
    the time to render, read back, compress, and composite images.  Stored
    as a double.
  \item[\CEnum{ICET\_VALID\_PIXELS\_NUM}] In conjunction with
    \CEnum{ICET\_VALID\_PIXELS\_OFFSET}, gives the range of valid pixels
    for the last image returned from \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame}.  Given the arrays of pixels returned with the
    \CFunc{icetImageGetColor} and \CFunc{icetImageGetDepth} functions, the
    valid pixels start at the pixel indexed by
    \CEnum{ICET\_VALID\_PIXELS\_OFFSET} and continue for
    \CEnum{ICET\_VALID\_PIXELS\_NUM}.  The tile to which these pixels
    belong are captured in the \CEnum{ICET\_VALID\_PIXELS\_TILE} state
    variable.  If the last call to \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame} did not return pixels for the local process,
    \CEnum{ICET\_VALID\_PIXELS\_NUM} is set to $0$.  This state variable is
    only useful when \CEnum{ICET\_COLLECT\_IMAGES} is off.  If on, it can
    be assumed that all display processes contain all pixels in the image
    (\CEnum{ICET\_VALID\_PIXELS\_NUM} is the number of pixels in the
    image), and all other processes have no pixel data.
  \item[\CEnum{ICET\_VALID\_PIXELS\_OFFSET}] In conjunction with
    \CEnum{ICET\_VALID\_PIXELS\_NUM}, gives the range of valid pixels for
    the last image returned from \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame}.  Given the arrays of pixels returned with the
    \CFunc{icetImageGetColor} and \CFunc{icetImageGetDepth} functions, the
    valid pixels start at the pixel indexed by
    \CEnum{ICET\_VALID\_PIXELS\_OFFSET} and continue for
    \CEnum{ICET\_VALID\_PIXELS\_NUM}.  The tile to which these pixels
    belong are captured in the \CEnum{ICET\_VALID\_PIXELS\_TILE} state
    variable.  This state variable is only useful when
    \CEnum{ICET\_COLLECT\_IMAGES} is off.  If on, it can be assumed that
    all display processes contain all pixels in the image
    (\CEnum{ICET\_VALID\_PIXELS\_OFFSET} is $0$), and all other processes
    have no pixel data.
  \item[\CEnum{ICET\_VALID\_PIXELS\_TILE}] Gives the tile for which the
    last image returned from \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame} contains pixels.  Each process has its own
    value.  If the last call to \CFunc{icetDrawFrame} or
    \CFunc{icetGLDrawFrame} did not return pixels for the local process,
    then this state variable is set to $-1$.  This state variable is only
    useful when \CEnum{ICET\_COLLECT\_IMAGES} is off.  If on, it can be
    assumed that all display processes have valid pixels for their
    respective display tiles, and all other processes have no pixel data.
  \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:
