icetDrawFrame(3)
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)