Provided by: paraview_5.4.1+dfsg3-1_amd64 bug

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.

       The  background_color argument specifies the desired background color for the image. It is
       given as an array of 4 floating point values specifying, in order, the red,  green,  blue,
       and alpha channels of the color in the range from 0.0 to 1.0.

       When rendering using a depth buffer, the background color is used to fill in empty regions
       of images. When rendering using  color  blending,  the  background  color  is  changed  to
       transparent  black  during rendering to prevent the background from being blended multiple
       times  from  different  renderings.  If  the  ICET_CORRECT_COLORED_BACKGROUND  feature  is
       enabled, this background color is blended back into the final composited image.

Return Value

       On  each  .igdisplay  processdisplay  process  (as  defined by icetAddTile), icetDrawFrame
       returns the fully composited image in an IceTImage object. 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
       or  composites 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  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 feature is enabled.

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),   icetCompositeImage(3),
       icetDrawCallback(3), icetGLDrawFrame(3), icetSingleImageStrategy(3), icetStrategy(3)

IceT Reference                          September 22, 2014                       icetDrawFrame(3)