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)