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)