NAME

       icetDrawFrame -- renders and composites a frame

Synopsis

       #include <IceT.h>

       IceTImage icetDrawFrame(
                                  const IceTDouble *   projection_matrix,
                                  const IceTDouble *   modelview_matrix,
                                  const IceTFloat *    background_color  );

Description

       Initiates  a  frame  draw  using the given transformation matrices (modelview and projection). If you are
       using OpenGL ,you should probably use the icetGLDrawFrame function and associated icetGLDrawCallback.

       Before IceT may render an image, the tiled display needs to be defined (using icetAddTile),  the  drawing
       function  needs  to  be  set  (using  icetDrawCallback),  and  composite  strategy  must  be  set  (using
       icetStrategy).  The single image sub-strategy may also optionally be set (using icetSingleImageStrategy).

       All processes in the current IceT context must call icetDrawFrame for it to complete.

       During compositing, IceT uses the given projection_matrix and modelview_matrix, as  well  as  the  bounds
       given  in  the  last  call to icetBoundingBox or icetBoundingVertices, to determine onto which pixels the
       local geometry projects. If the given matrices are not the same used in the rendering or the given bounds
       do not contain the geometry, IceT may clip the geometry in surprising ways. Furthermore, IceT will modify
       the projection_matrix for the drawing callback to change the projection onto (or in between) tiles. Thus,
       you should pass the desired projection_matrix to icetDrawFrame and then use the  version  passed  to  the
       drawing callback.

Return Value

       On  each  .igdisplay processdisplay process (as defined by icetAddTile, icetDrawFrame returns an image of
       the fully composited image. The contents of the image are undefined for any non-display process.

       If the ICET_COMPOSITE_ONE_BUFFER option is on and both  a  color  and  depth  buffer  is  specified  with
       icetSetColorFormatand  icetSetDepthFormat,then  the returned image might be missing the depth buffer. The
       rational behind this option is that often both the color and  depth  buffer  is  necessary  in  order  to
       composite  the color buffer, but the composited depth buffer is not needed. In this case, the compositing
       might save some time by not transferring depth information at the latter stage of compositing.

       The returned image uses memory buffers that will be reclaimed the next time IceT renders a frame. Do  not
       use this image after the next call to icetDrawFrame (unless you have changed the IceT context).

Errors

       ICET_INVALID_OPERATION
               Raised  if  the icetGLInitialize has not been called or if the drawing callback has not been set.
              Also can be raised if icetDrawFrame is  called  recursively,  probably  from  within  the  drawing
              callback.

       ICET_OUT_OF_MEMORY
               Not enough memory left to hold intermittent frame buffers and other temporary data.

       icetDrawFrame may also indirectly raise an error if there is an issue with the strategy or callback.

Warnings

       None.

Bugs

       If  compositing  with  color  blending  on, the image returned may have a black background instead of the
       background_color requested. This can be corrected  by  blending  the  returned  image  over  the  desired
       background. This will be done for you if the ICET_CORRECT_COLORED_BACKGROUND is on.

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

       icetAddTile(3),  icetBoundingBox(3),  icetBoundingVertices(3),  icetDrawCallback(3),  icetGLDrawFrame(3),
       icetSingleImageStrategy(3), icetStrategy(3)

IceT Reference                                   August  9, 2010                                icetDrawFrame(3)