NAME

       icetCompositeOrder -- specify the order in which images are composited

Synopsis

       #include <IceT.h>

       void icetCompositeOrder( const IceTInt * process_ranks );

Description

       If ICET_ORDERED_COMPOSITE is enabled and the current strategy supports ordered composition (verified with
       the  ICET_STRATEGY_SUPPORTS_ORDERING  state  variable,  then  the  order  which  images are composited is
       specified  with  icetCompositeOrder.   If  compositing  is   done   with   z-buffer   comparisons   (e.g.
       icetCompositeMode  is  called  with ICET_COMPOSITE_MODE_Z_BUFFER), then the ordering does not matter, and
       ICET_ORDERED_COMPOSITE should probably be disabled.  However, if compositing is done with color  blending
       (e.g. icetCompositeMode is called with ICET_COMPOSITE_MODE_BLEND), 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 a grid, 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 process_ranks should have  exactly  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 required by IceT .

       When ordering is on, it is accepted that 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 icetDataReplicationGroup), all processes are still expected to be
       listed in process_ranks.  Correct ordering can be achieved by ensuring that all processes in  each  group
       are listed in contiguous entries in process_ranks.

Errors

       ICET_INVALID_VALUE
               Not every entry in the parameter process_ranks was a unique, valid process rank.

Warnings

       None.

Bugs

       If an 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.

Copyright

       Copyright (C)2003 Sandia Corporation

       Under the terms of Contract DE-AC04-94AL85000  with  Sandia  Corporation,  the  U.S.  Government  retains
       certain rights in this software.

       This source code is released under the New BSD License.

See Also

       icetCompositeMode(3) icetStrategy(3)

IceT Reference                                   August  9, 2010                           icetCompositeOrder(3)