Ubuntu Manpage: icetDrawFrame -- renders and composites a frame

name
synopsis
description
return value
errors
warnings
bugs
copyright
see also

Provided by: paraview_5.10.0~rc1-1build3_amd64

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.