NAME¶
icetDrawCallback -- set a callback for drawing.
Synopsis¶
void icetDrawCallback( |
IceTDrawCallbackType |
callback ); |
Description¶
The
icetDrawCallback function sets a callback that is used to draw the
geometry from a given viewpoint. If you are using OpenGL ,you should probably
use the
icetGLDrawCallback function and associated
icetGLDrawFrame. These alternative functions automatically set up the
OpenGL state and retreive OpenGL buffers.
callback should be a function that renders an image of the local geometry
based on the provided transformation matrices and background color.
IceT
will call
callback during a call to
icetDrawFrame to create
the images for compositing.
callback will be called a minimum amount of
times. It may be called once. If none of the geometry projects on the display,
it may not be called at all. If rendering to a tiled display and the geometry
projects on multiple tiles, it may be called many times. The code in
callback should be prepared to be called an unpredictable amount of
times. For example, it should not attept to increment a frame counter and it
should leave the rendering system's state such that another view to the
geometry may be rendered.
callback takes two projection matrices:
projection_matrix and
modelview_matrix. Each of these arguments is a 16-value array that
represents a $4 *4$ transformation of homogeneous coordinates. The arrays
store the matrices in .igcolumn-major ordercolumn-major order.
Note that the
projection_matrix passed to
callback is liable to be
different than that passed to
icetDrawFrame. Make certain that
callback uses the modified
projection_matrix passed to it.
modelview_matrix is the same as that passed to
icetDrawFrame,
but also passed along for convienient reference.
Any pixel that does not have geometry rendered to it should be set to the
background_color passed to
callback. Likewise, any transparent
geometry should be blended against the
background_color. Note that the
background_color passed to
callback is liable to be different
than that passed to
icetDrawFrame.
callback is given
result, an image object allocated to the size of
the physical render size (see
icetPhysicalRenderSize). The dimensions
of the image can be queried with
icetImageGetWidth and
icetImageGetHeight. Pixels can be put in
result by getting the
color and/or depth buffers using the
icetImageGetColor and
icetImageGetDepth functions. Anything written to these buffers is
captured in the image object.
IceT passes
callback an image sized to the physical render space
to make indexing into it clearer and safer and to possibly render directly
into the image buffers. That said,
IceT might only be interested in a
subregion of the data. To make your callback more efficient,
IceT
provides
readback_viewport to specify the region of the image it
will read.
readback_viewport has four values. The first two values
specify the x and y pixel location of the lower left corner of the region of
interest. The last two values specify the width and height of the region of
interest. The callback only has to write valid pixels for this region of the
image. It is not an error to write values outside this region, but they will
be completely ignored.
The
callback function pointer is placed in the
ICET_DRAW_FUNCTION
state variable.
Errors¶
None.
Warnings¶
None.
Bugs¶
None known.
Notes¶
callback is tightly coupled with the bounds set with
icetBoundingVertices or
icetBoundingBox. If the geometry drawn
by
callback is dynamic (changes from frame to frame), then the bounds
may need to be changed as well. Incorrect bounds may cause the geometry to be
culled in surprising ways.
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¶
icetBoundingBox(3),
icetBoundingVertices(3),
icetDrawFrame(3),
icetPhysicalRenderSize(3)