NAME
icetDrawFrame -- renders and composites a frame
Synopsis
#include <GL/ice-t.h>
void icetDrawFrame(void);
Description
Initiates a frame draw using the current OpenGL transformation matrices
(modelview and projection).
IceT may render an image, the tile display needs to be defined (using
icetAddTile) and the drawing function needs to be set (using
icetDrawFunc). The composite strategy may also optionally be set
(using icetStrategy).
If ICET_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_DISPLAY_COLORED_BACKGROUND should also be enabled.
Displaying with ICET_DISPLAY_COLORED_BACKGROUND disabled may be
slightly faster (depending on graphics hardware) but can result in
black rectangles in the background. If ICET_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. If
ICET_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_DISPLAY is
disabled or the process is not displaying a tile.
Errors
ICET_INVALID_OPERATION
Raised if the drawing function 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.
Warnings
None.
Bugs
If compositing with color blending on, the image returned with
icetGetColorBuffermay have values of $<R, G, B, A >= <0, 0, 0, 0 >$and
the rest of the image may be blended with black rather than the correct
background color.
During compositing, image compression is employed that relies on
knowing the maximum possible value in the z-buffer. Unfortunately,
different rendering hardware can give different results for this value.
IceT tries to dermine this value up front by clearing the screen and
reading the z-buffer value, but this test sometimes fails, resulting in
a classification of background. The side effects of this are minimal,
and IceT usually quickly fixes the problem by continually checking
depth values.
Copyright
Copyright (C)2003 Sandia Corporation
Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive
license for use of this work by or on behalf of the U.S. Government.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that this Notice and any statement
of authorship are reproduced on all copies.
See Also
icetResetTiles(3), icetAddTile(3), icetBoundingBox(3),
icetBoundingVertices(3), icetDrawFunc(3), icetStrategy(3),
icetGetColorBuffer(3), icetGetDepthBuffer(3)
IceT Reference February 14, 2008 icetDrawFrame(3)