% -*- latex -*-


\setDate{April 12, 2006}
% The following must all be on one line for latex2man to work.
\begin{Name}{3}{icetCompositeOrder}{Kenneth Moreland}{\IceT Reference}{\CFunc{icetCompositeOrder} -- specify the order in which images are composited}

  \mansection{Synopsis}

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

  \textC{void }\CFunc{icetCompositeOrder}\textC{(} \textC{const GLint *}
  \CArg{process\_ranks} \textC{);}

  
  \mansection{Description}

  If \CEnum{ICET\_ORDERED\_COMPOSITE} is enabled and the current strategy
  supports ordered composition, then the order which images are composited
  are specified with \CFunc{icetCompositeOrder}.  If compositing is done
  with z-buffer comparisons (i.e. the depth buffer is selected as an input
  with \CFunc{icetInputOutputBuffers}), then the ordering does not matter,
  and \CEnum{ICET\_ORDERED\_COMPOSITE} should probably be disabled.
  However, if compositing is done with color blending (i.e. the depth
  buffer is \emph{not} selected as in input with
  \CFunc{icetInputOutputBuffers}), then the order in which the images are
  composed can drastically change the output.

  For ordered image compositing to work, the geometric objects rendered by
  processes must be arranged such that if the geometry of one process is
  ``in front'' of the geometry of another process for any camera ray, that
  ordering holds for all camera rays.  It is the application's
  responsibility to ensure that such an ordering exists and to find that
  ordering.  The easiest way to do this is to ensure that the geometry of
  each process falls cleanly into regions of an octree, k-d tree, or
  similar structure.

  Once the geometry order is determined for a particular rendering
  viewpoint, it is given to \IceT in the form of an array of ranks.  The
  parameter \CArg{process\_ranks} should have exactly
  \CEnum{ICET\_NUM\_PROCESSES} entries, each with a unique, valid process
  rank.  The first process should have the geometry that is ``in front'' of
  all others, the next directly behind that, and so on.  It should be noted
  that the application may actually impose only a partial order on the
  geometry, but that can easily be converted to the linear ordering requird
  by \IceT.

  When ordering is on, it is accepted that \CFunc{icetCompositeOrder} will
  be called in between every frame since the order of the geometry may
  change with the viewpoint.

  If data replication is in effect (see \CFunc{icetDataReplicationGroup}),
  all processes are still expected to be listed in \CArg{process\_ranks}.
  Correct ordering can be achieved by ensuring that all processes in each
  group are listed in contiguous entries in \CArg{process\_ranks}.


  \mansection{Errors}

  \begin{Description}[ICET\_INVALID\_OPERATION]
  \item[\CErrorEnum{ICET\_INVALID\_VALUE}]
    Not every entry in the parameter \CArg{process\_ranks} was a unique,
    valid process rank.
  \end{Description}


  \mansection{Warnings}

  None.


  \mansection{Bugs}

  If an \CErrorEnum{ICET\_INVALID\_VALUE} error is raised, internal arrays
  pertaining to the ordering of images may not be restored properly.  If
  such an error is raised, the function should be re-invoked with a valid
  ordering before preceding.  Unpredictable results may occur otherwise.


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