pfClear(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfClear(3pf)NAMEpfClear - Clear specified graphics buffers
FUNCTION SPECIFICATION
void pfClear(int which, const pfVec4 color);
PARAMETERS
which is a mask that specifies which buffers are to be cleared. which
is a bitwise OR of:
PFCL_COLOR Clear color buffer to color.
PFCL_DEPTH Clear depth buffer to maximum value of our
defined depth range.
PFCL_MSDEPTH Fast clear of the multisample depth buffer.
PFCL_STENCIL Clear stencil buffer to 0.
PFCL_DITHER Enable dithering during the color clear. By
default, pfClear turns off dithering for color
clears.
color specifies the red, green, blue, and alpha components of the color
buffer clear color. Each component is defined in the range 0.0 to
1.0. If color is NULL then a black fully opaque color will be
used.
DESCRIPTIONpfClear clears the buffers specified by which in the current graphics
window. The actual screen area cleared depends on many GL state settings
including viewport and screen or scissor mask (OpenGL glScissor), current
draw buffer (front, back, left, right, overlay, etc.), and the existence
of a depth buffer for PFCL_DEPTH and stencil buffer for PFCL_STENCIL.
See the OpenGL glClear(3g) reference page for more details.
If which includes PFCL_COLOR and color is NULL, then any selected color
buffer will be cleared to black fully opaque pixels using
glColor4f(0,0,0,1) in OpenGL.
PFCL_MSDEPTH has effect only when multisampling (See pfAntialias). In
this case, instead of writing the maximum depth value into each
individual pixel subsample, each pixel is "tagged" as having the maximum
depth value. This clear is much faster than a full depth buffer clear;
however, the color buffer is not cleared so results from previous frames
will be left in the color buffer if not redrawn. This requires that each
pixel in the viewport be covered by geometry. Often this is accomplished
by drawing one or more large background polygons (often textured) at the
far clip plane to "clear" the framebuffer to an interesting background
rather than depth buffer and then incurring the additional cost of
clearing drawing background polygons. This requires that the background
rendering disable depth buffer testing (e.g. glDepthFunc(GL_ALWAYS) in
Page 1
pfClear(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfClear(3pf)
OpenGL). Otherwise, a normal depth buffer clear will be required if
multisampling is not in use or not supported in the current framebuffer
configuration. Note that the background drawing should leave depth
buffering enabled so that it's depth values will be written.
The follow example shows how to clear all buffers with one pfClear call:
/*
* Clear color buffer to black, depth buffer to the maximum depth value,
* and stencil buffer to 0.
*/
pfClear(PFCL_DEPTH | PFCL_COLOR | PFCL_STENCIL, NULL);
pfClear is a display-listable command. If a pfDispList has been opened
by pfDispList::open, pfClear will not have immediate effect but will be
captured by the pfDispList and will only have effect when that pfDispList
is later drawn with pfDispList::draw.
NOTES
PFCL_MSDEPTH is only available on RealityEngine systems, and then only in
the multisample antialiasing mode. For performance reasons, the depth
buffer for the entire window rather than just the current viewport is
cleared with OpenGL on Indy, i.e. scissoring is disabled.
SEE ALSO
pfAntialias, pfDispList, glClear, glDepthFunc, clear, multisample,
gconfig, zclear, zfunction, czclear
Page 2
