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.