NAME

       icetGLDrawCallback -- set a callback for drawing with OpenGL .

Synopsis

       #include <IceTGL.h>

       typedef void (* IceTGLDrawCallbackType)( void );

       void icetGLDrawCallback(   IceTGLDrawCallbackType   callback  );

Description

       The  icetGLDrawCallback  function sets a callback that is used to draw the geometry from a
       given viewpoint. It will be implicitly called from within icetGLDrawFrame.

       callback should be a function that issues appropriate OpenGL calls to draw geometry in the
       current  OpenGL  context.  After  callback  is  called, the image left in the frame buffer
       specified by icetGLSetReadBuffer will be read back for compositing.

       callback should not modify the GL_PROJECTION_MATRIX as this  would  cause  IceT  to  place
       image  data in the wrong location in the tiled display and improperly cull geometry. It is
       acceptable to add transformations to GL_MODELVIEW_MATRIX, but the bounding vertices  given
       with  icetBoundingVertices or icetBoundingBox are assumed to already be transformed by any
       such changes to the modelview matrix.  Also, GL_MODELVIEW_MATRIX must be  restored  before
       the  draw  function  returns. Therefore, any changes to GL_MODELVIEW_MATRIX are to be done
       with care and should be surrounded by a pair of glPushMatrix and glPopMatrix functions.

       It is also important that callback not  attempt  the  change  the  clear  color.  In  some
       composting  modes,  IceT  needs  to  read,  modify, and change the background color. These
       operations will be lost if  callback  changes  the  background  color,  and  severe  color
       blending artifacts may result.

       IceT  may  call callback several times from within a call to icetGLDrawFrame or not at all
       if the current bounds lie outside the current  viewpoint.  This  can  have  a  subtle  but
       important   impact  on  the  behavior  of  callback.   For  example,  counting  frames  by
       incrementing a frame counter in callback is obviously wrong (although you could count  how
       many  times  a  render occurs).  callback should also leave OpenGL in a state such that it
       will be correct for a subsequent run of callback.  Any matrices or  attributes  pushed  in
       callback  should  be  popped  before callback returns, and any state that is assumed to be
       true on entrance to callback should also be true on return.

       The callback function pointer is placed in the ICET_GL_DRAW_FUNCTION state variable.

       icetGLDrawCallback is similar to icetDrawCallback.  The difference is  that  the  callback
       set   by   icetGLDrawCallback   is  used  by  icetGLDrawFrame  and  the  callback  set  by
       icetDrawCallback is used by icetDrawFrame.

Errors

       ICET_INVALID_OPERATION
               Raised if the icetGLInitialize has not been called.

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), icetDrawCallback(3), icetGLDrawFrame(3)

IceT Reference                           August  9, 2010                    icetGLDrawCallback(3)