NAME

       icetGLDrawFrame -- renders and composites a frame using OpenGL

Synopsis

       #include <IceTGL.h>

       void  icetGLDrawFrame( void );

Description

       Initiates  a  frame  draw  using the current OpenGL transformation matrices (modelview and
       projection).

       Before  IceT  may  render  an  image,  the  tiled  display  needs  to  be  defined  (using
       icetAddTile),  the  drawing  function  needs  to  be  set  (using icetGLDrawCallback), and
       composite strategy must be set (using icetStrategy).  The single  image  sub-strategy  may
       also optionally be set (using icetSingleImageStrategy).

       All processes in the current IceT context must call icetGLDrawFrame for it to complete.

       The  OpenGL  projection  matrix  and  modelview matrix must be set using glLoadMatrix or a
       number of other functions.  Likewise,  the  OpenGL  background  color  must  be  set  with
       glClearColor.  IceT will use the matrices to determine what pixels need to be rendered and
       composited. IceT will also modify the projection matrix to project onto  (or  in  between)
       tiles.

       If  ICET_GL_DISPLAY  is  enabled,  then  the fully composited image is written back to the
       OpenGL framebuffer for display. It is the application's responsibility to synchronize  the
       processes  and  swap  front  and  back  buffers.  If the OpenGL background color is set to
       something other than black, ICET_GL_DISPLAY_COLORED_BACKGROUND  should  also  be  enabled.
       Displaying   with  ICET_GL_DISPLAY_COLORED_BACKGROUND  disabled  may  be  slightly  faster
       (depending on graphics hardware) but can result in black rectangles in the background.  If
       ICET_GL_DISPLAY_INFLATE  is  enabled  and the size of the renderable window (determined by
       the current OpenGL viewport) is greater than that of the tile being  displayed,  then  the
       image  will  first be ``inflated'' to the size of the actual display.  This inflation will
       be assisted  by  texture  hardware  if  ICET_GL_DISPLAY_INFLATE_WITH_HARDWARE  is  on.  If
       ICET_GL_DISPLAY_INFLATE  is disabled, the image is drawn at its original resolution at the
       lower left corner of the display.

       The image remaining in the frame buffer is undefined if ICET_GL_DISPLAY is disabled or the
       process is not displaying a tile.

Errors

       ICET_INVALID_OPERATION
               Raised  if  the  drawing  callback  has  not  been  set.  Also  can  be  raised if
              icetDrawFrame is called recursively, probably from within the drawing callback.

       ICET_OUT_OF_MEMORY
               Not enough memory left to hold intermittent  frame  buffers  and  other  temporary
              data.

       icetGLDrawFrame  may also indirectly raise an error if there is an issue with the strategy
       or callback.

Warnings

       None.

Bugs

       If compositing with color blending on, the image returned  may  have  a  black  background
       instead  of the background_color requested. This can be corrected by blending the returned
       image  over   the   desired   background.   This   will   be   done   for   you   if   the
       ICET_CORRECT_COLORED_BACKGROUND is on.

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

       icetAddTile(3),     icetBoundingBox(3),     icetBoundingVertices(3),     icetDrawFrame(3),
       icetGLDrawCallback(3), icetSingleImageStrategy(3), icetStrategy(3)

IceT Reference                          September 20, 2010                     icetGLDrawFrame(3)