pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)NAME
pfWindow, pfChooseWinFBConfig, pfGetCurWin, pfInitGfx - GL-independent
window creation/management routines
FUNCTION SPECIFICATION
#include <Performer/pr/pfWindow.h>
pfWindow::pfWindow();
pfType* pfWindow::getClassType(void);
void pfWindow::setAspect(int x, int y);
void pfWindow::setFBConfig(pfFBConfig config);
void pfWindow::setFBConfigAttrs(int *attr);
void pfWindow::setFBConfigData(void *data);
void pfWindow::setFBConfigId(int id);
void pfWindow::setFullScreen(void);
void pfWindow::setGLCxt(pfGLContext gCxt);
void pfWindow::setIndex(int index);
void pfWindow::setMode(int mode, int val);
void pfWindow::setName(const char *name);
void pfWindow::setOrigin(int xo, int yo);
void pfWindow::setOriginSize(int xo, int yo, int xs,
int ys);
void pfWindow::setOverlayWin(pfWindow *ow);
void pfWindow::setScreen(int s);
void pfWindow::setShare(uint mode);
void pfWindow::setSize(int xs, int ys);
void pfWindow::setStatsWin(pfWindow *statsWin);
void pfWindow::setWSConnectionName(const char *name);
void pfWindow::setWSDrawable(pfWSConnection dsp,
pfWSDrawable xWin);
Page 1
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
void pfWindow::setWSWindow(pfWSConnection dsp,
pfWSWindow xWin);
void pfWindow::setWinList(pfList *wl);
void pfWindow::setWinType(uint type);
void pfWindow::getAspect(int *x, int *y);
void pfWindow::getCurOriginSize(int *xo, int *yo, int *xs,
int *ys);
void pfWindow::getCurScreenOriginSize(int *xo, int *yo,
int *xs, int *ys);
pfState* pfWindow::getCurState(void);
pfFBConfig pfWindow::getFBConfig(void);
int* pfWindow::getFBConfigAttrs(void);
void* pfWindow::getFBConfigData(void);
int pfWindow::getFBConfigId(void);
pfGLContext pfWindow::getGLCxt(void);
int pfWindow::getIndex(void);
int pfWindow::getMode(int mode);
const char* pfWindow::getName(void);
void pfWindow::getOrigin(int *xo, int *yo);
pfWindow* pfWindow::getOverlayWin(void);
int pfWindow::getScreen(void);
void pfWindow::getScreenOrigin(int *xo, int *yo);
pfWindow* pfWindow::getSelect(void);
uint pfWindow::getShare(void);
void pfWindow::getSize(int *xs, int *ys);
pfWindow* pfWindow::getStatsWin(void);
const char * pfWindow::getWSConnectionName(void);
Page 2
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
pfWSDrawable pfWindow::getWSDrawable(void);
pfWSWindow pfWindow::getWSWindow(void);
pfList* pfWindow::getWinList(void);
uint pfWindow::getWinType(void);
int pfWindow::attach(pfWindow *win1);
pfFBConfig pfChooseWinFBConfig(pfWindow *win, int *attr);
pfFBConfig pfWindow::chooseFBConfig(int *attr);
void pfWindow::close(void);
void pfWindow::closeGL(void);
int pfWindow::isOpen(void);
int pfWindow::isManaged(void);
int pfWindow::mQuery(int *which, int *dst);
void pfWindow::open(void);
static pfWindow* pfWindow::openNewNoPort(const char *name, int screen);
int pfWindow::query(int which, int *dst);
pfWindow* pfWindow::select(void);
void pfWindow::attachSwapGroup(pfWindow *win1);
void pfWindow::inSwapGroup(void);
void pfWindow::setSwapBarrier(int barrier);
int pfWindow::getSwapBarrier(void);
void pfWindow::swapBuffers(void);
pfWindow * pfGetCurWin(void);
void pfInitGfx(void);
/* typedef of X-based Performer Types */
typedef Display *pfWSConnection;
typedef XVisualInfo pfFBConfig;
typedef Window pfWSWindow;
typedef Drawable pfWSDrawable;
Page 3
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
typedef GLXFBConfigSGIX pfGLXFBConfig;
typedef GLXContext pfGLContext;
PARENT CLASS FUNCTIONS
The OpenGL Performer class pfWindow is derived from the parent class
pfObject, so each of these member functions of class pfObject are also
directly usable with objects of class pfWindow. This is also true for
ancestor classes of class pfObject.
void* pfObject::operator new(size_t);
void* pfObject::operator new(size_t, void *arena);
void* pfObject::operator new(size_t, pfFluxMemory *fmem);
void pfObject::setUserData(void *data);
void pfObject::setUserData(int slot, void *data);
void* pfObject::getUserData(pfObject *obj);
void* pfObject::getUserData(pfObject *obj, int slot);
int pfObject::getNumUserData();
Since the class pfObject is itself derived from the parent class
pfMemory, objects of class pfWindow can also be used with these functions
designed for objects of class pfMemory.
void* pfMemory::getData(const void *ptr);
pfType * pfMemory::getType();
int pfMemory::isOfType(pfType *type);
int pfMemory::isExactType(pfType *type);
const char * pfMemory::getTypeName();
int pfMemory::copy(pfMemory *src);
int pfMemory::compare(const pfMemory *mem);
void pfMemory::print(uint which, uint verbose, char *prefix,
FILE *file);
int pfMemory::getArena(void *ptr);
void* pfMemory::getArena();
int pfMemory::ref();
int pfMemory::unref();
int pfMemory::unrefDelete();
int pfMemory::unrefGetRef();
int pfMemory::getRef();
int pfMemory::checkDelete();
int pfMemory::isFluxed();
void * pfMemory::getArena();
int pfMemory::getSize();
DESCRIPTION
These functions provide a single API for creating and managing windows.
new(arena) allocates a pfWindow from the specified memory arena, or from
the heap if arena is NULL. new allocates a pfWindow from the default
memory arena (see pfGetSharedArena). Like other pfObjects, pfWindows
Page 4
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
cannot be created statically, on the stack or in arrays.
pfWindow::getClassType returns the pfType* for the class pfWindow. The
pfType* returned by pfWindow::getClassType is the same as the pfType*
returned by invoking the virtual function getType on any instance of
class pfWindow. Because OpenGL Performer allows subclassing of built-in
types, when decisions are made based on the type of an object, it is
usually better to use the member function isOfType to test if an object
is of a type derived from a Performer type rather than to test for strict
equality of the pfType*'s.
pfWindow::setAspect sets the aspect ratio of the pfWindow to be x:y.
pfWindow::getAspect returns the aspect X and Y components of the pfWindow
in x and y.
pfWindow::setFullScreen will cause the window to be a full screen window
and change its size appropriately. Future queries of size and origin
will reflect this new full screen size.
pfWindow::setFBConfig sets the framebuffer configuration for the pfWindow
to be that specified by config which must be an XVisualInfo* or an
GLXFBConfigSGIX. OpenGL Performer will derive an X visual from config if
necessary. This will determine the framebuffer configuration used to
create the graphics context. pfWindow::getFBConfig will return the
XVisualInfo* for the visual of the pfWindow.
pfWindow::setFBConfigAttrs provides a window system independent list of
attribute tokens, attr, to describe the desired framebuffer configuration
of the pfWindow. The attribute list format is the same as the SGI GLX
attribute format for OpenGL, but with matching PFFB_* tokens that can be
used with OpenGL in place of the GLX_* tokens. See the glXChooseVisual
man pages for more information. pfWindow::getFBConfigAttrs will return
the attribute array corresponding to the visual of win.
pfWindow::setFBConfigData can be used to provide GL dependent data
directly to the OpenGL framebuffer configuration routine.
pfWindow::getFBConfigData can be used to get back GL dependent data
resulting from these calls. See the GLXgetconfig(3g) and GLXlink(3g) man
pages for more information.
pfWindow::setFBConfigId allows you to directly set the OpenGL X visual id
to be used in configuring the resulting OpenGL/X window.
pfWindow::getFBConfigId will return the current OpenGL visual id of the
window (or -1 if the id is not known) See the XVisualIDFromVisual(3X11)
and XGetVisualInfo(3X11) man pages for more information about X visuals.
pfWindow::setGLCxt sets the graphics context of the pfWindow to be gCxt.
If the graphics context window of the pfWindow has been set,
pfWindow::open on the pfWindow will use that context and not create
another. pfWindow::getGLCxt will return the graphics context of the
pfWindow.
Page 5
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
pfWindow::setIndex sets the alternate configuration window list index of
the pfWindow to be index. If index is greater than or equal to zero, it
will select an alternate configuration window from the pfWindow
pfWinList. index may also select one of the standard windows:
PFWIN_STATS_WIN, PFWIN_OVERLAY_WIN, and the default, PFWIN_GFX_WIN. The
window indexing is only one level deep - if the selected pfWindow has a
window list and index, it is ignored and the graphics window and context
of that pfWindow is used to determine the drawing area.
pfWindow::getIndex will return the current index for the pfWindow.
pfWindow::getSelect will return the pointer to the currently selected
pfWindow for the pfWindow.
pfWindow::setWinList sets a pfWindow list of alternate configuration
windows for the pfWindow to be the pfList of pfWindow*s, wlist.
pfWindow::getWinList will return the current window list. These alternate
configuration windows are assumed to have the same pfWSWindow parent
window as the base pfWindow.
pfWindow::setMode sets the pfWindow mode specified by mode of the
pfWindow to val. mode may be one of:
PFWIN_ORIGIN_LL will cause placement of win to be relative
to the lower left corner of it and its
parent window.
PFWIN_NOBORDER will cause the window to not have the
window system border around the outside of
its drawing area. To have a drawing area
that is truly full screen, this mode should
be set.
PFWIN_AUTO_RESIZE will cause sub-pfWindows of the pfWindow
who also have this mode set to be
automatically reconfigured to match the
size and position of win. This includes
the PFWIN_OVERLAY_WIN, the PFWIN_STATS_WIN,
and the current selected window from the
pfWindow list. The selection of a new
window from the pfWindow list will also be
automatically sized and positioned if it is
using the PFWIN_AUTO_RESIZE mode. This
mode is on by default.
PFWIN_HAS_OVERLAY will cause pfWindow::open to automatically
create and open (if necessary) an overlay
window for the main pfWindow. If the
window is of type PFWIN_AUTO_RESIZE, the
overlay window will be automatically
configured to keep the same size/position
as the main window.
Page 6
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
PFWIN_EXIT Causes the window to receive special
ClientMessage X events when the user
selects "Quit" or "Exit" from the window
manager border menu on the window. The
XEvent.xclient.message_type field will be
set to point to the X atom for
"WM_PROTOCOLS" and XEvent.xclient.data.l[0]
will be set to point to the X atom,
"WM_DELETE_WINDOW". See the examples below
and the XClientMessageEvent man page for
more information.
pfWindow::getMode will return the value of the requested mode in mode.
pfWindow::setName sets the name of a pfWindow. By default, pfWindows have
no name. pfWindow::getName returns the name of a pfWindow.
pfWindow::setOrigin sets the origin of the pfWindow the pfWindow to be
(xo,yo), relative to its parent window. pfWindow::getOrigin returns the
origin set by pfWindow::setOrigin. If the pfWindow mode is
PFWIN_ORIGIN_LL, the origin of the window is considered to be the lower-
left corner. Otherwise, the origin of the window is considered to be the
X-style upper-left corner. pfWindow::setSize sets the size of the
pfWindow the pfWindow to be x by y. pfWindow::getSize returns the size
of the pfWindow set by pfWindow::setSize, by pfWindow::open, or by
pfWindow::getCurOriginSize. pfWindow::setOriginSize sets both the origin
and size of the pfWindow.
pfWindow::getCurOriginSize returns the current origin and size of the
pfWindow the pfWindow, if open, otherwise it returns the origin and size
set by pfWindow::setOrigin, pfWindow::setSize, or
pfWindow::setOriginSize. The internal origin and size of the pfWindow
will be updated. This routine accesses the graphics context and/or the X
server and is slow on a window of type PFWIN_TYPE_X.
pfWindow::getCurScreenOrigin returns the cached screen relative origin of
the pfWindow, if open, from the last time the window size was set and
then selected. Otherwise it returns the origin and size set by
pfWindow::setOrigin.
pfWindow::getCurScreenOriginSize returns the current screen-relative
origin and size of the pfWindow, if open. Otherwise it returns the
origin and size set by pfWindow::setOrigin, pfWindow::setSize, or
pfWindow::setOriginSize. For windows of type PFWIN_TYPE_X, it must make
expensive queries to the X server and can be very slow.
pfWindow::setOverlayWin sets the pfWindow overlay to be the associated
PFWIN_OVERLAY_WIN window for the main drawing pfWindow, the pfWindow.
This pfWindow is selected on the pfWindow with
pfWindow::setIndex(PFWIN_OVERLAY_WIN). overlay should have the same
parent X window as the pfWindow. pfWindow::getOverlayWin will return the
PFWIN_OVERLAY_WIN pfWindow.
Page 7
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
pfWindow::setScreen sets the screen of the pfWindow to be screen. The
screen selection takes effect upon pfWindow::open. A screen will be set
by pfWindow::open if on was not previously set. The screen of a pfWindow
cannot be changed once set. pfWindow::getScreen will return the screen
of a pfWindow.
pfWindow::setShare sets the attributes that are to be shared by pfWindows
of the share group of the pfWindow to be the bitmask specified by share.
Some share attributes, such as PFWIN_SHARE_TYPE and PFWIN_SHARE_GFX_OBJS,
must be specified before windows in the share group are opened. The
following tokens specify the attributes that may be shared among
pfWindows and may be or-ed together to from share:
PFWIN_SHARE_MODE
PFWIN_SHARE_FBCONFIG
PFWIN_SHARE_GL_CXT
PFWIN_SHARE_GL_OBJS
PFWIN_SHARE_STATE
PFWIN_SHARE_OVERLAY_WIN
PFWIN_SHARE_STATS_WIN
PFWIN_SHARE_TYPE
PFWIN_SHARE_WSDRAWABLE
PFWIN_SHARE_WSWINDOW
pfWindow::getShare will return the share bitmask of the pfWindow.
pfWindow::setStatsWin sets the pfWindow statsWin to be the associated
PFWIN_OVERLAY_WIN window for the main drawing pfWindow, the pfWindow.
This pfWindow is selected on the pfWindow with
pfWindow::setIndex(PFWIN_STATS_WIN). statsWin should have the same
parent X window as the pfWindow. pfWindow::getStatsWin will return the
PFWIN_STATS_WIN pfWindow.
pfWindow::setWinType sets the type of a pfWindow where type is an or-ed
bitmask that may contain the type constants listed below.
pfWindow::getWinType returns the type of a pfWindow. The type of a
pfWindow only takes effect by the call of pfWindow::open. The type of an
open pfWindow cannot be changed. The pfWindow type attributes all start
with PFWIN_TYPE_ and are:
PFWIN_TYPE_NOPORT
The resulting window will have a graphics context but will not
be mapped onto the screen. Windows of type PFWIN_TYPE_NOPORT
are useful for queries about the graphics resources of the
Page 8
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
system and are needed for accessing the Video Sync Clock. To
facilitate this, there is the special utility routine,
pfWindow::openNewNoPort. Also, see the man pages for
pfInitVClock, and pfQuerySys. If this token is specified, all
other type tokens are ignored.
PFWIN_TYPE_X
The window opened will be an X window. OpenGL windows are
always of type PFWIN_TYPE_X. Windows of this type have as
their pfWSWindow an X window (pfWindow::setWSWindow). The
pfWSDrawable that is attached to the graphics context is by
default an X window (but can be set as an X Pixmap --
pfWindow::setWSDrawable) and has a framebuffer configuration
matching that specified by the pfWindow. If the pfWSDrawable
of the pfWindow is a separate X window from the parent
pfWSWindow X window (as is created by default), the
pfWSDrawable window can actually be changed for one with a
different framebuffer configuration without ugly flashing. To
facilitate this, pfWindows may also have a list of windows (-
pfWindow::setWinList) that may have different framebuffer
configuration types and pfWSDrawable X windows but all share
the same parent X pfWSWindow.
PFWIN_TYPE_OVERLAY
The pfWindow the pfWindow will be given an appropriate
framebuffer configuration, if not already set, that will
support the standard overlay draw configuration at the time of
the call to pfWindow::open. For X windows, an X colormap will
also be created and attached to the corresponding X window.
See the man pages for XCreateWindow, and XCreateColormap for
more information.
PFPWIN_TYPE_PBUFFER
The window drawable will be created in a pbuffer. For this,
you must also specify an GLXFBConfigSGIX with
pfWindow::setFBConfig before the window is opened.
PFWIN_TYPE_STATS
The pfWindow the pfWindow will be given a framebuffer
configuration, if one has not already been specified through
pfWindow::setFBConfig or pfWindow::chooseFBConfig, that will
support the current pfStats::setHwAttr configuration at the
time of the call to pfWindow::open. See the pfStats::setHwAttr
man page for information on different statistics attributes and
their framebuffer requirements.
PFPWIN_TYPE_UNMANAGED
OpenGL Performer will not do automatic X window management on
this window. This includes size and position tracking,
resizing of alternate configuration windows, and swapbuffers.
OpenGL Performer will still make the graphics context of this
window current if it is selected. pfWindows with drawables that
Page 9
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
are of type GLXPbufferSGIX or Pixmap are automatically made
unmanaged.
pfWindow::setWSWindow sets the main window system window of the pfWindow
to be xWin This routine is only relevant for pfWindows of type
PFWIN_TYPE_X. The WSWindow of a pfWindow, if not NULL, is used to manage
the size and position of the pfWindow. The WSWindow should also be the
parent window of the WSDrawable window of the pfWindow. The WSWindow
should be shared amongst all sub-pfWindows, such as the overlay window,
the stats window, and any windows n the pfWindow list. If the WSWindow
of the pfWindow has been set, pfWindow::open on the pfWindow will use
that X window and not create another. pfWindow::getWSWindow will return
the X Window of the pfWindow.
pfWindow::setWSDrawable sets the graphics X drawable of the pfWindow to
be drawable. The drawable of a pfWindow is attached to the graphics
context and may be an X Pixmap, a GLXPbufferSGIX, or an X Window. If
provided as an X Window, it should be a child of the WSWindow of the
pfWindow. If a drawable has not been provided by the time of
pfWindow::open, an X Window will be created by default. If the graphics
drawable of the pfWindow has been set, pfWindow::open on the pfWindow
will use that X window and not create another. pfWindow::getWSDrawable
will return the drawable of the pfWindow. pfWindow::getCurWSDrawable
will return the drawable of the currently selected window of the window
list.
pfWindow::setWSConnectionName allows you to specify the exact window
server and default screen for the successive opening of the window. This
can be used for specifying remote displays or on machines running more
than one window server. pfWindow::getWSConnectionName will return the
name specifying the current window server target.
pfWindow::attach puts win1, and its current share group, in the pfWindow
share group of the pfWindow. The attributes of the pfWindow will be
copied to win1 and all of the windows in win1's previous share group.
pfWindows cannot be removed from a share group.
pfWindow::chooseFBConfig will select a framebuffer configuration for the
pfWindow, constrained by current settings, such as type and the
framebuffer configuration attributes, on the pfWindow. Additionally, the
selection of the framebuffer configuration will be relative to the screen
of the pfWindow. If the screen has not been set, it will be determined
from the default screen of the current pfWSConnection or DISPLAY
environment variable. The return value is the resulting pfFBConfig, or
NULL, indicating failure. For X windows, pfWindow::chooseFBConfig and
pfWindow::getFBConfig returns the resulting XVisualInfo*.
pfWindow::open creates a graphics context and window, constrained by the
settings of the pfWindow on the current selected display via
pfGetCurWSConnection. Attributes of the pfWindow that are not set are
created and set as necessary. If the graphics window and context are not
set, they will be created.
Page 10
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
If the pfWindow framebuffer configuration is not set (-
pfWindow::setFBConfig or pfWindow::chooseFBConfig), the graphics window
will get the default rendering framebuffer configuration for its current
type (pfWindow::setWinType). For a rendering graphics window of type
PFWIN_TYPE_X, if the graphics drawable has been set via
pfWindow::setWSDrawable, the framebuffer configuration of that window is
used for the graphics context. Otherwise, a default rendering
framebuffer configuration for the current machine will be chosen via (-
pfChooseFBConfig). not have multisample buffers by default. All
pfWindows are automatically initialized with pfInitGfx upon opening with
pfWindow::open.
If the x or y size of the pfWindow is <= 0, then a rubber-band window
will be created for the user to determine the origin and size of the
window, constrained by the pfWindow aspect if set (pfWindow::setAspect).
If the size of the pfWindow is <= 0 but the origin is < 0, then the
graphics window will be opened with fixed size but allow the user to
place the window. The pfWindow origin and size may both be internally set
by pfWindow::open. If the PFWIN_HAS_OVERLAY mode has been set, a
PFWIN_OVERLAY_WIN will be automatically created (if not already set,
pfWindow::setOverlayWin) and opened. If the pfWindow has a pfWindow list
(pfWindow::setWinList) and the current pfWindow index is not
PFWIN_GFX_WIN, then the selected pfWindow from the list will be opened. A
pfState is automatically created for the pfWindow and the pfWindow is
made the current libpr pfWindow. pfWindow::getCurState will return the
current pfState of the pfWindow. pfGetCurWin will return the pointer to
the current libpr pfWindow.
pfWindow::close will destroy the graphics context of the open the
pfWindow. If the pfWindow is of type PFWIN_TYPE_X, its X windows will be
unmapped. pfWindow::closeGL will destroy the current graphics context and
graphics X window but leaves the top level X window in tact.
pfWindow::isOpen returns the open status of the pfWindow.
pfWindow::isManaged returns whether or not of the pfWindow is of type
PFPWIN_TYPE_UNMANAGED.
pfWindow::query takes a window configuration query token which and writes
into dst the value for the corresponding configuration of the the opened
pfWindow. The pfWindow query token may be one of:
PFQWIN_RGB_BITS returns the number of bits per R_G_B color
component allocated in the main color
buffer.
PFQWIN_ALPHA_BITS returns the number of bits allocated for
alpha in the main color buffer.
PFQWIN_CI_BITS returns the number of bits for colorindex
indices.
Page 11
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
PFQWIN_DEPTH_BITS returns the number of framebuffer bits
allocated for Z.
PFQWIN_MIN_DEPTH_VAL returns the minimum representable Z depth
value.
PFQWIN_MAX_DEPTH_VAL returns the maximum representable Z depth
value.
PFQWIN_MS_SAMPLES returns the number of multisample samples.
PFQWIN_STENCIL_BITS returns the number of bits in the stencil
buffer.
PFQWIN_STEREO returns whether the window has stereo
buffers allocated.
PFQWIN_DOUBLEBUFFER returns whether the window has double-
buffered color buffers allocated.
PFQWIN_NUM_AUX_BUFFERS returns the number of auxiliary color
buffers allocated for the window.
PFQWIN_LEVEL returns the level of window planes (0 is
normal drawing level, negative for underlay
and positive for overlay).
PFQWIN_ACCUM_RGB_BITS returns the number of bits per R_G_B color
component allocated in the accumulation
buffer.
PFQWIN_ACCUM_ALPHA_BITS returns the number of bits of alpha
allocated in the accumulation buffer.
pfWindow::mQuery takes an NULL-terminated array of query tokens and a
destination buffer and will do multiple queries. The return value will
be the number of bytes successfully written. This routine is more
efficient than pfWindow::query if multiple queries are desired.
pfWindow::attachSwapGroup will place the windows in the swap group of
win1 in the swap group of win0. Windows in a swap group will always
swap buffers at the same time. If two windows are in the same SwapGroup,
but not on the same screen, then OpenGL Performer will automatically hook
up a named SwapBarrier that is used to synchronize across graphics
pipelines. This also requires system configuration (see the notes below).
pfWindow::inSwapGroup returns a boolean indicating if the window has been
attached to a hardware SwapGroup. This attachment will not happen until
a call to pfWindow::select.
pfWindow::setSwapBarrier let you attach the SwapGroup that contains the
window to a barrier. If barrier is (-1), OpenGL Performer will pick a
barrier name. Currently on InfiniteReality there is only one barrier
Page 12
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
available and will be name (1). This might be necessary if you have
other non-Performer windows hooked up to an OpenGL barrier with
glXBindSwapBarrierSGIX(3G) and want to add OpenGL Performer windows,
first to a swap group, then to the named barrier. Additionally, this is
useful for InfiniteReality Calligraphic setup which uses the SwapReady
interface to synchronize raster and calligraphic displays.
pfWindow::getSwapBarrier return 0 if no barrier is set, or the barrier
number otherwise.
pfWindow::swapBuffers causes the currently selected front and back
buffers of the normal framebuffer of an open window to be exchanged
during the next vertical retrace period.
pfGetCurWin will return the pointer current OpenGL Performer pfWindow.
This a window is made the current window when it is opened with
pfWindow::open or selected with pfWindow::select.
pfInitGfx will configure the current graphics context correctly for
OpenGL Performer rendering operation and is called automatically when
pfWindows are opened. It will enable z-buffer depth testing, viewport
clipping, and subpixel vertex accuracy mode. The Viewing projection
will be a two-dimensional one-to-one orthographic mapping from eye
coordinates to window coordinates with distances to near and far clipping
planes -1 and 1, respectively. The model matrix will be the current
matrix and will be initialized to the identity matrix. It is highly
recommended that a libpr application managing its own windows call
pfInitGfx for its normal drawing.
NOTES
X Window origin and size: There are some subtle issues in the management
of origin and size of X windows. With X windows, it can be very expensive
to obtain the current screen relative origin of a window, particularly if
the window is in a hierarchy. Therefore, the origin of a window is
defined to be that relative to it's parent window (which can be the
screen). Additionally, there are a bevy of routines for getting the
window origin. User code should not rely on knowning the up to date
screen relative origin but should be window-coordinate relative to be
efficient and reliable.
X Framebuffer Configuration: The selection of framebuffer configurations
for X windows uses the default GL selection function
glXChooseVisual(3X11). This function returns the maximum possible
framebuffer configuration matching the requested attributes. However,
this may not be the optimal configuration for performance. One such
example occurs with OpenGL on RealityEngine: when requesting four
multisample subsamples and a depth buffer of 24 bits, a depth buffer of
32 bits will be returned which has measurably slower fill rate than a 24
bit depth buffer. If the default functions are not returning the desired
framebuffer configuration, you can do your own X visual selection and set
the visual id or the visual itself on the pfWindow with
pfWindow::setFBConfigId and pfWindow::setFBConfig respectively.
Page 13
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
Additionally, libpfutil provides an OpenGL visual chooser,
pfuChooseFBConfig, that limits the performance critical attributes:
multisamples, depth, RGB color, and stencil.
A special case for framebuffer configuration exists for the Extreme
graphics platforms. On these platforms, the default framebuffer
configuration has NO allocated stencil bits because stencil bits will
reduce depth buffer resolution. The user may explicitly request stencil
bits if desired.
EXAMPLES
This example creates a pfWindow structure and opens and initializes the
window for Performer drawing.
{
pfWindow *win;
pfInitState();
win = new pfWindow;
win->setName("Performer");
win->open(); /* create window and rendering context */
......
}
This example is a more detailed example for creating a window of pre-
defined size and position. It will have an overlay window created
automatically when the window is opened.
{
pfWindow *win;
pfWindow *overlay;
WSConnection dsp;
pfInitState();
win = new pfWindow;
win->setName("Performer");
win->setOriginSize(0, 0, 500, 500);
win->setWinType(PFWIN_TYPE_X | PFWIN_TYPE_OVERLAY);
win->open(); /* create window, overlay, and rendering context */
/* get back some useful things created by Performer */
overlay = win->getOverlayWin();
/* get back Performer's internal shared display
connection to use for event handling */
dsp = pfGetCurWSConnection();
}
Page 14
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C++ Reference Pages pfWindow(3pf)
This example demonstrates how to catch the X ClientMessage event when a
window of a pfWindow of type PFWIN_TYPE_EXIT is killed via the Quit or
Exit option in the window manager menu on the window border.
{
WSConnection theDisplay = pfGetCurWSConnection();
Atom WMProtocols = XInternAtom(theDisplay, "WM_PROTOCOLS", 1);
ATOM WMDeleteWindow = XInternAtom(theDisplay, "WM_DELETE_WINDOW", 1);
....
/* in X event handling loop */
{
XEvent event;
XNextEvent(theDisplay, &event);
/* in X event handling switch */
case ClientMessage:
if ((event.xclient.message_type == wm_protocols) &&
(event.xclient.data.l[0] == wm_delete_window)) {
/* handle window exit */
}
break;
.....
}
}
Swap groups can contain windows rendering to different graphics pipelines
to force that their double-buffering is synchronized so that they are
guaranteed to always be displaying the same frame and have their hardware
swapbuffers happen simultaneously. For this to work, you must first have
the graphics pipelines genlocked. See the genlock(7) man page for more
informations. Next, you must connect the proper cable between the
SwapReady connectors on the graphics pipelines. On the InfiniteReality
this is a simple BNC cable of any Ohms. The SwapGroup functionality on
pfWindows is only supported under OpenGL operation.
BUGS
Detach from share groups and swap groups is not supported.
SEE ALSO
pfStats, pfState, pfSelectWSConnection, pfGetCurWSConnection,
pfuChooseFBConfig, GLXgetconfig, GLXlink, XCreateWindow,
XGetWindowAttributes, XGetVisualInfo, XVisualIDFromVisual
Page 15
