icetGetColorBuffer(3)

NAME
icetGetColor/DepthBuffer - 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. ICE-T 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 icetGetBooleanv with 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
icetGetColorBuffer returns 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.

icetGetDepthBuffer returns 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 ICE-T state.

The memory returned by icetGetColorBuffer and icetGetDepthBuffer need 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 subsequent ICE-T 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 © 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, icetInputOutputBuffers, icetGet