NAME
icetGetColorBuffer,icetGetDepthBuffer-- retrieves the last computed
color or depth buffer.
Synopsis
#include <GL/ice-t.h>
GLubyte *icetGetColorBuffer ( void );
GLuint *icetGetDepthBuffer ( void );
Description
Returns a buffer containing the result of the image composition
performed by the last call to icetDrawFrame. Be aware that a color or
depth buffer may not have been computed with the last call to
icetDrawFrame. IceT avoids the computation and network transfers for
any unnecessary buffers unless specifically requested otherwise with
the flags given to the icetInputOutputBuffers function. Use a call to
icetGetBooleanvwith a value of ICET_COLOR_BUFFER_VALID or
ICET_DEPTH_BUFFER_VALID to determine whether either of these buffers
are available. Attempting to get a nonexistent buffer will result with
a warning being emitted and NULL returned.
Return Value
icetGetColorBufferreturns the color buffer for the displayed tile.
Each pixel value can be assumed to be four consecutive bytes in the
buffer. The pixels are also always aligned on 4-byte boundaries. The
format of the color buffer is defined by the state parameter
ICET_COLOR_FORMAT, which is typically either GL_RGBA, GL_BGRA, or
GL_BGRA_EXT.
icetGetDepthBufferreturns the depth buffer for the displayed tile.
Depth values are stored as 32-bit integers.
The width and the height of the buffer are determined by the width and
the height of the displayed tile at the time icetDrawFrame was called.
If the tile layout is changed since the last call to icetDrawFrame, the
dimensions of the buffer returned may not agree with the dimensions
stored in the current IceT state.
The memory returned by icetGetColorBufferand icetGetDepthBufferneed
not, and should not, be freed. It will be reclaimed in the next call to
icetDrawFrame. Expect the data returned to be obliterated on the next
call to icetDrawFrame.
Errors
None.
Warnings
ICET_INVALID_VALUE
The appropriate buffer is not available, either because it was
not computed or it has been obliterated by a subsequent IceT
computation.
Bugs
The returned image may have a value of $(R, G, B, A) = (0, 0, 0, 0)$
for a pixel instead of the true background color. This can usually be
corrected by replacing all pixels with an alpha value of 0 with the
background color.
The buffers are stored in a shared memory pool attached to a particular
context. As such, the buffers are not copied with the state. Also,
because they are shared, it is conceivable that the buffers will be
reclaimed before the next call to icetDrawFrame. If this should
happen, the ICET_COLOR_BUFFER_VALID and ICET_DEPTH_BUFFER_VALID state
variables will be set accordingly.
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
icetDrawFrame(3), icetInputOutputBuffers(3), icetGet(3)
IceT Reference February 14, 2008 icetGetColorBuffer(3)