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 icetGLInitialize has not been called or if the drawing callback has
              not been set. Also can be raised if icetGLDrawFrame 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 26, 2014                     icetGLDrawFrame(3)