pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)NAME
pfNewWin, pfGetWinClassType, pfWinAspect, pfWinFBConfig,
pfWinFBConfigAttrs, pfWinFBConfigData, pfWinFBConfigId, pfWinFullScreen,
pfWinGLCxt, pfWinIndex, pfWinList, pfWinMode, pfWinName, pfWinOrigin,
pfWinOriginSize, pfWinOverlayWin, pfWinScreen, pfWinShare, pfWinSize,
pfWinStatsWin, pfWinType, pfWinWSConnectionName, pfWinWSDrawable,
pfWinWSWindow, pfGetWinAspect, pfGetWinCurOriginSize,
pfGetWinCurScreenOriginSize, pfGetWinCurState, pfGetWinCurWSDrawable,
pfGetWinFBConfig, pfGetWinFBConfigAttrs, pfGetWinFBConfigData,
pfGetWinFBConfigId, pfGetWinGLCxt, pfGetWinIndex, pfGetWinList,
pfGetWinMode, pfGetWinName, pfGetWinOrigin, pfGetWinOverlayWin,
pfGetWinScreen, pfGetWinScreenOrigin, pfGetWinSelect, pfGetWinShare,
pfGetWinSize, pfGetWinStatsWin, pfGetWinType, pfGetWinWSConnectionName,
pfGetWinWSDrawable, pfGetWinWSWindow, pfAttachWin, pfChooseWinFBConfig,
pfCloseWin, pfCloseWinGL, pfIsWinOpen, pfIsManagedWin, pfMQueryWin,
pfOpenNewNoPortWin, pfOpenWin, pfQueryWin, pfSelectWin,
pfAttachWinSwapGroup, pfWinInSwapGroup, pfWinSwapBarrier,
pfGetWinSwapBarrier, pfSwapWinBuffers, pfGetCurWin, pfInitGfx - GL-
independent window creation/management routines
FUNCTION SPECIFICATION
#include <Performer/pr.h>
pfWindow* pfNewWin(void *arena);
pfType* pfGetWinClassType(void);
void pfWinAspect(pfWindow *win, int x, int y);
void pfWinFBConfig(pfWindow *win, pfFBConfig config);
void pfWinFBConfigAttrs(pfWindow *win, int *attr);
void pfWinFBConfigData(pfWindow *win, void *data);
void pfWinFBConfigId(pfWindow *win, int id);
void pfWinFullScreen(pfWindow *win);
void pfWinGLCxt(pfWindow *win, pfGLContext gCxt);
void pfWinIndex(pfWindow *win, int index);
void pfWinList(pfWindow *win, pfList *wlist);
void pfWinMode(pfWindow *win, int mode, int val);
void pfWinName(pfWindow *win, const char *name);
void pfWinOrigin(pfWindow *win, int xo, int yo);
Page 1
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
void pfWinOriginSize(pfWindow *win, int xo, int yo, int xs,
int ys);
void pfWinOverlayWin(pfWindow *win, pfWindow *ow);
void pfWinScreen(pfWindow *win, int s);
void pfWinShare(pfWindow *win, uint mode);
void pfWinSize(pfWindow *win, int xs, int ys);
void pfWinStatsWin(pfWindow *win, pfWindow *ow);
void pfWinType(pfWindow *win, uint type);
void pfWinWSConnectionName(const pfWindow *win,
const char *name);
void pfWinWSDrawable(pfWindow *win, pfWSConnection dsp,
pfWSDrawable xWin);
void pfWinWSWindow(pfWindow *win, pfWSConnection dsp,
pfWSWindow xWin);
void pfGetWinAspect(const pfWindow *win, int *x, int *y);
void pfGetWinCurOriginSize(pfWindow *win, int *xo, int *yo,
int *xs, int *ys);
void pfGetWinCurScreenOriginSize(pfWindow *win, int *xo,
int *yo, int *xs, int *ys);
pfState* pfGetWinCurState(const pfWindow *win);
pfWSDrawable pfGetWinCurWSDrawable(const pfWindow *win);
pfFBConfig pfGetWinFBConfig(const pfWindow *win);
int* pfGetWinFBConfigAttrs(const pfWindow *win);
void* pfGetWinFBConfigData(pfWindow *win);
int pfGetWinFBConfigId(const pfWindow *win);
pfGLContext pfGetWinGLCxt(const pfWindow *win);
int pfGetWinIndex(const pfWindow *win);
pfList* pfGetWinList(const pfWindow *win);
Page 2
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
int pfGetWinMode(const pfWindow *win, int mode);
const char* pfGetWinName(const pfWindow *win);
void pfGetWinOrigin(const pfWindow *win, int *xo, int *yo);
pfWindow* pfGetWinOverlayWin(const pfWindow *win);
int pfGetWinScreen(const pfWindow *win);
void pfGetWinScreenOrigin(const pfWindow *win, *xo, *yo);
pfWindow* pfGetWinSelect(pfWindow *win);
uint pfGetWinShare(const pfWindow *win);
void pfGetWinSize(const pfWindow *win, int *xs, int *ys);
pfWindow* pfGetWinStatsWin(const pfWindow *win);
uint pfGetWinType(const pfWindow *win);
const char* pfGetWinWSConnectionName(const pfWindow *win);
pfWSDrawable pfGetWinWSDrawable(const pfWindow *win);
pfWSWindow pfGetWinWSWindow(const pfWindow *win);
int pfAttachWin(pfWindow *win0, pfWindow *win1);
pfFBConfig pfChooseWinFBConfig(pfWindow *win, int *attr);
void pfCloseWin(pfWindow *win);
void pfCloseWinGL(pfWindow *win);
int pfIsWinOpen(pfWindow *win);
int pfIsManagedWin(pfWindow *win);
int pfMQueryWin(const pfWindow *win, int *which, int *dst);
pfWindow* pfOpenNewNoPortWin(const char *name, int screen);
void pfOpenWin(pfWindow *win);
int pfQueryWin(const pfWindow *win, int which, int *dst);
pfWindow* pfSelectWin(pfWindow *win);
Page 3
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
void pfAttachWinSwapGroup(pfWindow* win0, pfWindow *win1);
int pfWinInSwapGroup(pfWindow* win);
void pfWinSwapBarrier(pfWindow* win, int barrier);
int pfGetWinSwapBarrier(pfWindow* win);
void pfSwapWinBuffers(pfWindow *win);
pfWindow * pfGetCurWin(void);
void pfInitGfx(void);
/* typedef of X-based Performer Types */
typedef Display *pfWSConnection;
typedef XVisualInfo pfFBConfig;
typedef Window pfWSWindow;
typedef Drawable pfWSDrawable;
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. Casting an object of
class pfWindow to an object of class pfObject is taken care of
automatically. This is also true for casts to objects of ancestor
classes of class pfObject.
void pfUserDataSlot(pfObject *obj, int slot, void *data);
void pfUserData(pfObject *obj, void *data);
void* pfGetUserDataSlot(pfObject *obj, int slot);
void* pfGetUserData(pfObject *obj);
int pfGetNumUserData(pfObject *obj);
int pfGetNamedUserDataSlot(const char *name);
const char* pfGetUserDataSlotName(int slot);
int pfGetNumNamedUserDataSlots(void);
int pfGetGLHandle(pfObject *obj);
int pfDeleteGLHandle(pfObject *obj);
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.
Page 4
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
pfType * pfGetType(const void *ptr);
int pfIsOfType(const void *ptr, pfType *type);
int pfIsExactType(const void *ptr, pfType *type);
const char * pfGetTypeName(const void *ptr);
int pfRef(void *ptr);
int pfUnref(void *ptr);
int pfUnrefDelete(void *ptr);
int pfUnrefGetRef(void *ptr);
int pfGetRef(const void *ptr);
int pfCopy(void *dst, void *src);
int pfDelete(void *ptr);
int pfIsFluxed(void *ptr);
int pfCompare(const void *ptr1, const void *ptr2);
void pfPrint(const void *ptr, uint which, uint verbose,
FILE *file);
void * pfGetArena(void *ptr);
PARAMETERS
win identifies a pfWindow.
DESCRIPTION
These functions provide a single API for creating and managing windows.
pfNewWin creates and returns a handle to a pfWindow. arena specifies a
malloc arena out of which the pfWindow is allocated or NULL for
allocation off the process heap.
pfGetWinClassType returns the pfType* for the class pfWindow. The
pfType* returned by pfGetWinClassType is the same as the pfType* returned
by invoking pfGetType 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 pfIsOfType 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.
pfWinAspect sets the aspect ratio of win to be x:y. pfGetWinAspect
returns the aspect X and Y components of win in x and y.
pfWinFullScreen 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.
pfWinFBConfig sets the framebuffer configuration for win 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. pfGetWinFBConfig will return the XVisualInfo* for the visual of
win.
pfWinFBConfigAttrs provides a window system independent list of attribute
tokens, attr, to describe the desired framebuffer configuration of win.
Page 5
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
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. pfGetWinFBConfigAttrs will return the attribute array
corresponding to the visual of win.
pfWinFBConfigData can be used to provide GL dependent data directly to
the OpenGL framebuffer configuration routine. pfGetWinFBConfigData 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.
pfWinFBConfigId allows you to directly set the OpenGL X visual id to be
used in configuring the resulting OpenGL/X window. pfGetWinFBConfigId
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.
pfWinGLCxt sets the graphics context of win to be gCxt. If the graphics
context window of win has been set, pfOpenWin on win will use that
context and not create another. pfGetWinGLCxt will return the graphics
context of win.
pfWinIndex sets the alternate configuration window list index of win 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. pfGetWinIndex will return the
current index for win. pfGetWinSelect will return the pointer to the
currently selected pfWindow for win.
pfWinList sets a pfWindow list of alternate configuration windows for win
to be the pfList of pfWindow*s, wlist. pfGetWinList will return the
current window list. These alternate configuration windows are assumed to
have the same pfWSWindow parent window as the base pfWindow.
pfWinMode sets the pfWindow mode specified by mode of win 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.
Page 6
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
PFWIN_AUTO_RESIZE will cause sub-pfWindows of win 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 pfOpenWin 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.
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.
pfGetWinMode will return the value of the requested mode in mode.
pfWinName sets the name of a pfWindow. By default, pfWindows have no
name. pfGetWinName returns the name of a pfWindow.
pfWinOrigin sets the origin of the pfWindow win to be (xo,yo), relative
to its parent window. pfGetWinOrigin returns the origin set by
pfWinOrigin. 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.
pfWinSize sets the size of the pfWindow win to be x by y. pfGetWinSize
returns the size of the pfWindow set by pfWinSize, by pfOpenWin, or by
pfGetWinCurOriginSize. pfWinOriginSize sets both the origin and size of
win.
pfGetWinCurOriginSize returns the current origin and size of the pfWindow
win, if open, otherwise it returns the origin and size set by
pfWinOrigin, pfWinSize, or pfWinOriginSize. The internal origin and size
of win 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.
Page 7
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
pfGetWinCurScreenOrigin returns the cached screen relative origin of win,
if open, from the last time the window size was set and then selected.
Otherwise it returns the origin and size set by pfWinOrigin.
pfGetWinCurScreenOriginSize returns the current screen-relative origin
and size of win, if open. Otherwise it returns the origin and size set
by pfWinOrigin, pfWinSize, or pfWinOriginSize. For windows of type
PFWIN_TYPE_X, it must make expensive queries to the X server and can be
very slow.
pfWinOverlayWin sets the pfWindow overlay to be the associated
PFWIN_OVERLAY_WIN window for the main drawing pfWindow, win. This
pfWindow is selected on win with pfWinIndex(win, PFWIN_OVERLAY_WIN).
overlay should have the same parent X window as win. pfGetWinOverlayWin
will return the PFWIN_OVERLAY_WIN pfWindow.
pfWinScreen sets the screen of win to be screen. The screen selection
takes effect upon pfOpenWin. A screen will be set by pfOpenWin if on was
not previously set. The screen of a pfWindow cannot be changed once set.
pfGetWinScreen will return the screen of a pfWindow.
pfWinShare sets the attributes that are to be shared by pfWindows of the
share group of win 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
pfGetWinShare will return the share bitmask of win.
pfWinStatsWin sets the pfWindow statsWin to be the associated
PFWIN_OVERLAY_WIN window for the main drawing pfWindow, win. This
Page 8
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
pfWindow is selected on win with pfWinIndex(win, PFWIN_STATS_WIN).
statsWin should have the same parent X window as win. pfGetWinStatsWin
will return the PFWIN_STATS_WIN pfWindow.
pfWinType sets the type of a pfWindow where type is an or-ed bitmask that
may contain the type constants listed below. pfGetWinType returns the
type of a pfWindow. The type of a pfWindow only takes effect by the call
of pfOpenWin. 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
system and are needed for accessing the Video Sync Clock. To
facilitate this, there is the special utility routine,
pfOpenNewNoPortWin. 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 (pfWinWSWindow). The pfWSDrawable
that is attached to the graphics context is by default an X
window (but can be set as an X Pixmap -- pfWinWSWindow) 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 (pfWinList) that may have different framebuffer
configuration types and pfWSDrawable X windows but all share
the same parent X pfWSWindow.
PFWIN_TYPE_OVERLAY
The pfWindow win 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
pfOpenWin. 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 pfWinFBConfig
before the window is opened.
PFWIN_TYPE_STATS
The pfWindow win will be given a framebuffer configuration, if
one has not already been specified through pfWinFBConfig or
Page 9
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
pfChooseWinFBConfig, that will support the current
pfStatsHwAttr configuration at the time of the call to
pfOpenWin. See the pfStatsHwAttr 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
are of type GLXPbufferSGIX or Pixmap are automatically made
unmanaged.
pfWinWSWindow sets the main window system window of win 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 Win. 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 win has been set,
pfOpenWin on win will use that X window and not create another.
pfGetWinWSWindow will return the X Window of win.
pfWinWSDrawable sets the graphics X drawable of win 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 pfOpenWin, an X Window will be created
by default. If the graphics drawable of win has been set, pfOpenWin on
win will use that X window and not create another. pfGetWinWSDrawable
will return the drawable of win. pfGetWinCurWSDrawable will return the
drawable of the currently selected window of the window list.
pfWinWSConnectionName 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. pfGetWinWSConnectionName will return the name specifying
the current window server target.
pfAttachWin puts win1, and its current share group, in the pfWindow share
group of win0. The attributes of win0 will be copied to win1 and all of
the windows in win1's previous share group. pfWindows cannot be removed
from a share group.
pfChooseWinFBConfig will select a framebuffer configuration for win,
constrained by current settings, such as type and the framebuffer
configuration attributes, on win. Additionally, the selection of the
framebuffer configuration will be relative to the screen of win. 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
Page 10
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
value is the resulting pfFBConfig, or NULL, indicating failure. For X
windows, pfChooseWinFBConfig and pfGetWinFBConfig returns the resulting
XVisualInfo*.
pfOpenWin creates a graphics context and window, constrained by the
settings of win on the current selected display via pfGetCurWSConnection.
Attributes of win that are not set are created and set as necessary. If
the graphics window and context are not set, they will be created.
If the pfWindow framebuffer configuration is not set (pfWinFBConfig or
pfChooseWinFBConfig), the graphics window will get the default rendering
framebuffer configuration for its current type (pfWinType). For a
rendering graphics window of type PFWIN_TYPE_X, if the graphics drawable
has been set via pfWinWSDrawable, 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
pfOpenWin.
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 (pfWinAspect). 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
pfOpenWin. If the PFWIN_HAS_OVERLAY mode has been set, a
PFWIN_OVERLAY_WIN will be automatically created (if not already set,
pfWinOverlayWin) and opened. If win has a pfWindow list (pfWinList) 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.
pfGetWinCurState will return the current pfState of win. pfGetCurWin
will return the pointer to the current libpr pfWindow.
pfCloseWin will destroy the graphics context of the open win. If win is
of type PFWIN_TYPE_X, its X windows will be unmapped. pfCloseWinGL will
destroy the current graphics context and graphics X window but leaves the
top level X window in tact.
pfIsWinOpen returns the open status of win.
pfIsManagedWin returns whether or not of win is of type
PFPWIN_TYPE_UNMANAGED.
pfQueryWin takes a window configuration query token which and writes into
dst the value for the corresponding configuration of the the opened
pfWindow win. 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.
Page 11
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
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.
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.
pfMQueryWin 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 pfQueryWin if multiple queries are desired.
pfAttachWinSwapGroup 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).
pfWinInSwapGroup returns a boolean indicating if win has been attached to
Page 12
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
a hardware SwapGroup. This attachment will not happen until a call to
pfSelectWin.
pfWinSwapBarrier let you attach the SwapGroup that contains win to a
barrier. If barrier is (-1), OpenGL Performer will pick a barrier name.
Currently on InfiniteReality there is only one barrier 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. pfGetWinSwapBarrier return 0 if no
barrier is set, or the barrier number otherwise.
pfSwapWinBuffers 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 pfOpenWin
or selected with pfSelectWin.
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
Page 13
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
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 pfWinFBConfigId
and pfWinFBConfig respectively. 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. This window will be an OpenGL/X window.
{
pfWindow *win;
pfInitState();
win = pfNewWin(NULL);
pfWinName(win, "Performer");
pfOpenWin(win); /* 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;
pfWSConnection dsp;
pfInitState();
win = pfNewWin(NULL);
pfWinName(win, "Performer");
pfWinOriginSize(win, 0, 0, 500, 500);
pfWinType(win, PFWIN_TYPE_X);
pfWinMode(win, PFWIN_HAS_OVERLAY, PF_TRUE);
pfOpenWin(win); /* create window, overlay, and rendering context */
/* get back some useful things created by Performer */
overlay = pfGetWinOverlayWin(win);
Page 14
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)
/* get back Performer's internal shared display
connection to use for event handling */
dsp = pfGetCurWSConnection();
}
This example demonstrates how to catch the X ClientMessage event when a
window of a pfWindow of mode PFWIN_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.
Page 15
pfWindow(3pf) OpenGL Performer 3.2.2 libpr C Reference Pages pfWindow(3pf)SEE ALSO
pfStatsHwAttr, pfNewState, pfSelectWSConnection, pfGetCurWSConnection,
pfuChooseFBConfig, GLXgetconfig, GLXlink, XCreateWindow,
XGetWindowAttributes, XGetVisualInfo, XVisualIDFromVisual
Page 16
