NAME

       icetDrawCallback -- set a callback for drawing.

Synopsis

       #include <IceT.h>

       typedef void (*IceTDrawCallbackType)(
                                               const IceTDouble *   projection_matrix,
                                               const IceTDouble *   modelview_matrix,
                                               const IceTFloat *    background_color,
                                               const IceTInt *      readback_viewport,
                                               IceTImage            result  )

       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 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)