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)