bionic (3) icetDrawCallback.3.gz
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) IceT Reference August 23, 2010 icetDrawCallback(3)