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)