The pfWindow object provides an efficient windowing interface between your application and the X Window System or the Microsoft Windows GUI. pfWindows typically create an X window (an HWND on Microsoft Windows) or can also be configured to embed your rendering area within a window created with Motif^® or other windowing toolkits. libpr provides utilities to shield you from the differences between the different types of windows and guide you in your dealings with the window system. pfWindows also keep track of your graphics state: they include a pfState which is automatically initialized when you open a window and switched for you when you change windows. Simple libpr windowing support centers around the pfWindow. The libpf windowing support utilizes a pfWindow as part of a pfPipeWindow.

OpenGL Performer automatically configures and initializes your window so that it will be ready to start rendering efficiently. In the simplest case, pfWindows make creating a graphics application that can run on any SGI machine with OpenGL a snap. pfWindows do not limit your ability to configure any part or all of your windowing environment yourself; you can use the libpr pfWindows to manage your GL windows even if you create and configure the actual windows yourself.

A pfWindow structure is created with pfNewWin(). It can then be immediately opened with pfOpenWin(). Example 16-1 shows the most basic pfWindow operations in libpr program: to open and clear a pfWindow and swap front and back color buffers.

int main (void)
{
     pfWindow *win;
     /* Initialize Performer */
     pfInit();
     pfInitState(NULL);
 
     /* Create and open a Window */
     win = pfNewWin(NULL);
     pfWinName(win, “Hello from OpenGL Performer”);
     pfOpenWin();
 
     /* Rendering loop */
     while (1)
     {
         /* Clear to black and max depth */
         pfClear(PFCL_COLOR | PFCL_DEPTH, NULL);
         ...
         pfSwapWinBuffers(win);
     }
}

The pfWindow in Example 16-1 will have the following configuration:

Typically, pfWindows go through a bit more initialization than that of Example 16-1. The pfWindow type, set with pfWinType(), is a bitmask that selects the window system interface and the type of rendering window. Table 16-1 lists the possible selectors that can be ORed together for specification of the window type.

The selection of screen can be done explicitly with pfWinScreen(), or implicitly by opening a connection to the window system using pfOpenScreen() with the desired screen as the default screen. A window system connection can communicate with any screen on the system; the default screen only determines the screen for windows that do not have a screen explicitly set for them. Only one window system connection should be opened for a process. See “Communicating with the Window System” later in this section for details on efficient interaction with the window system.

The position and/or size, is set with  pfWinOriginSize(). If the x and y components of the origin are (-1), the window will open with position undefined for the user to place. If the x or y components of the size are (-1), the window will open with both position and size undefined (the default) for the user to place and stretch. On IRIX and Linux, the X window manager may override negative origins and place the window at (0,0). If the window is already opened when pfWinOriginSize() is called, the window will be reconfigured to the specified origin and size upon the next pfSelectWin(). Similarly, pfWinFullScreen() causes a window to open as full screen or to become full screen upon the next call to pfSelectWin(). A full screen window will have its border automatically removed so that the drawing area truly gets the full rendering surface. The routines for querying the position and size work a bit differently than the pattern established by the rest of libpr get and set pairs of routines. This is because a user may change the origin or size independently of the program and under certain conditions, querying the true current X window size and origin can be expensive. pfGetWinOrigin() and pfGetWinSize() will always be fast and returns the last explicitly set origin and size, such as by pfOpenWin(), pfWinOriginSize(), or pfWinFullScreen(). If the window origin or size has been changed, but not through a pfWindow routine, the values returned by pfGetWinOrigin() and pfGetWinSize() may not be correct. pfGetWinCurOriginSize() returns an accurate size and origin relative to the pfWindow parent. For X windows, note that it requires an expensive query to the X server and should not be done in real-time situations. pfGetWinCurScreenOriginSize() returns the size and the screen-relative origin of the pfWindow. As with pfGetWinCurOriginSize(), this command will be quite expensive and is not recommended accept for rare use or initialization purposes.

pfPipeWindows, discussed in Chapter 17, “pfPipeWindows and pfPipeVideoChannels”, take advantage of the multiprocessed libpf environment to always be able to return an accurate window size and origin relative to the window parent. However, even for pfPipeWindows, getting a screen-relative origin can be an expensive operation.

Write programs that are window-relative and do not depend on knowing the current exact location of a window relative to its parent or screen.

OpenGL Performer provides a default framebuffer configurations for the current graphics hardware platform for the standard window types: normal rendering, statistics (stats), and overlay. You may want to define your own framebuffer configuration, such as single-buffered, stereo, etc. You can use utilities in libpr to help you with this task, or create your own framebuffer configuration structure with X utilities, or even create the window yourself and apply it to the pfWindow. pfOpenWin() respects any specified framebuffer configuration. Additionally, pfOpenWin() uses any window or graphics context that is assigned to it and only creates what is undefined.

pfWinFBConfigAttrs() can be used to specify an array of framebuffer attribute tokens listed in Table 16-2. The tokens correspond to OpenGL/X tokens. Note that if an attribute array is specified, the tokens modify configuration with no attributes set, not the default OpenGL Performer framebuffer configuration.

If you desire more control over the exact framebuffer configuration of your pfWindow, you have several options. For OpenGL/X windows you can provide the appropriate framebuffer description for the current GL operation to the pfWindow using pfWinFBConfig(). X uses visuals to describe available framebuffer configurations. XVisualInfo pointer with XGetVisualInfo() returns a list of all visuals on the system and you can search through them to find the appropriate configuration. On IRIX-based systems, OpenGL/X also uses GLXFBConfigSGIX to describe framebuffer configurations. You can select either the visual or the GLXFBConfigSGIX for your window and set it on the pfWindow with pfWinFBConfig(). pfGetWinFBConfig() always returns the corresponding X visual.

libpr also offers utilities for creating framebuffer configurations (pfFBConfig) independently of a pfWindow. pfChooseFBConfig() takes an attribute array of tokens from Table 16-2 and will return a pfFBConfig structure that can be used with your pfWindows, or with X Windows created outside of libpr, such as with Motif. You may get back a framebuffer configuration that is better than the one you requested. OpenGL Performer will give you back the maximum framebuffer configuration that meets your request that will not add any serious performance degradations. There are specific machine-dependent instances where, for performance reasons, we do limit the framebuffer configuration. See the man page for pfChooseWinFBConfig() for the specific details. The libpfutil utility pfuChooseFBConfig() in /usr/share/Performer/src/lib/libpfutil/xwin.c (IRIX and Linux) and %PFROOT%\Src\lib\libpfutil\xwin.c (Microsoft Windows) provides a limiting framebuffer configuration selector, complete with source code.

You can use pfQuerySys() to query particular framebuffer resources in the current hardware configuration and then use pfQueryWin() to query your resulting framebuffer configuration.

---

Note: This is an advanced topic.

---

For IRIX and Linux, libpr allows you to use X window handles and OpenGL/X graphics contexts to create your own windows and to set them on the pfWindow. These handles can be assigned to the pfWindow with pfWinWSDrawable() or pfWinGLCxt(). For Microsoft Windows, you can do the same, but you must use HWNDs (instead of X window handles) and OpenGL/WGL graphics contexts.

pfOpenWin() will automatically call pfInitGfx() and will automatically create a new pfState for your window. If you have your own window management and do not call pfOpenWin(), then you should definitely call pfInitGfx() to initialize the window's graphics state for OpenGL Performer rendering. You will also need to call pfNewState() to create a pfState for OpenGL Performer's state management.

For X windows, OpenGL Performer maintains two windows and a graphics context. The top level X window is placed on the screen and is the one that you should use in your application for selecting X events. This top level window is very lightweight and has minimal resources allocated to it. OpenGL Performer then maintains a separate X window that is a child of the parent X window and is the one that is attached to the graphics context. This allows you to select different framebuffer resources for the same drawing area by just selecting a different graphics window and graphics context pair for the parent X window. pfWindows directly support this functionality and this is discussed in the next section, “Manipulating a pfWindow”. Finally, with OpenGL, you may choose to draw to a different X Drawable than a window. X windows are created with the X function XCreateWindow(). OpenGL graphics contexts are created with glXCreateContext(). The parent X Window can be set with pfWinWSWindow(), the graphics window or X Drawable is set with pfWinWSDrawable() and can be an X window, pbuffer, or pixmap. The graphics context is set with pfWinGLCxt(). OpenGL Performer defines the following window-system-independent types defined in Table 16-3. If you create your own window but want to use pfQueryWin(), you must also provide the framebuffer configuration information with pfWinFBConfig(). pfQueryWin() uses the internally stored visual.

Windows are opened with pfOpenWin() and closed with pfCloseWin(). When a window is closed, its graphics context is deleted. If you have multiple windows, you select the window to draw to with pfSelectWin(). Multiple windows can be made more efficient using share groups configured with pfWinShare() to share hardware resources. Multiple windows can be made to have swapbuffers execute simultaneously through window swap groups created with  pfAttachWinSwapGroup(). There are also some additional modes on pfWindows to control their behavior under various operations. This section goes through the basics of these important features.

There are some modes you can set that can effect the general look and behavior of your window and alternate configuration windows. These boolean modes can be individually set and changed at any time with pfWinMode() and the tokens in Table 16-4.

You can communicate with a local or remote window server by means of a window system connection, a pfWSConnection (in X, also known as a Display connection). You can use your pfWSConnection for selecting X events for your window, as is demonstrated in Example 16-4.

libpr offers several utilities for creating a connection to a window server. A given connection can communicate with any screen managed by that window server so usually a process only needs one connection. A process should not share the connection of another process, so you will need a connection per process. Typically, there is exactly one window server on a machine but that is not required. libpr maintains a pfWSConnection for the current process. By default, this connection obeys the setting of the DISPLAY environment variable which can point to a window server on a local or a remote machine. The current connection can be requested with pfGetCurWSConnection() and can be set with pfSelectWSConnection(). Whenever possible, use this connection to limit the total number of open connections. pfOpenScreen() is a convenient mechanism for opening a connection with a specified default screen. pfOpenWSConnection() allows you to specify the exact name specifying the desired target for the connection. Both pfOpenScreen() and pfOpenWSConnection() allow you to specify if you would like the new connection to automatically be made the current libpr pfWSConnection; this is recommended.

Example 16-2 demonstrates the creation of a window with a default overlay window.

int main (void)
{
    pfWindow *win, *over;
    /* Initialize Performer */
    pfInit();
    pfInitState(NULL);
 
    /* Initialize the window. */
     win = pfNewWin(NULL);
     pfWinOriginSize(win, 100, 100, 500, 500);
     pfWinName(win, “OpenGL Performer”);
     pfWinType(win, PFWIN_TYPE_X);
     pfWinMode(win, PFWIN_HAS_OVERLAY, 1);
     pfOpenWin(win);
     /* First select and draw into the overlay window */
     pfWinIndex(win, PFWIN_OVERLAY_WIN);
     /* Select causes the index to be applied */
     pfSelectWin(win); 
     ...
     /* Then select the main gfx window */
     pfWinIndex(win, PFWIN_GFX_WIN);
     pfSelectWin(win); 
     ...
}

Example 16-3 demonstrates creating a custom overlay window and is taken from the sample program /usr/share/Performer/src/pguide/libpr/C/winfbconfig.c for IRIX and Linux and %PFROOT%\Src\pguide\libpr\C\winfbconfig.c for Microsoft Windows.

static int OverlayAttrs[] = {
 PFFB_LEVEL, 1, /* Level 1 indicates overlay visual */
 PFFB_BUFFER_SIZE, 8, 
 None,
};
 
int main (void)
{
    pfWindow *win, *over;
    /* Initialize Performer */
    pfInit();
    pfInitState(NULL);
 
    /* Initialize the window. */
     win = pfNewWin(NULL);
     pfWinOriginSize(win, 100, 100, 500, 500);
     pfWinName(win, “OpenGL Performer”);
     pfWinType(win, PFWIN_TYPE_X);
     pfWinMode(win, PFWIN_HAS_OVERLAY, 1);
 
     over = pfNewWin(NULL);
     pfWinName(over, “OpenGL Performer Overlay”);
     pfWinType(over, PFWIN_TYPE_X | PFWIN_TYPE_OVERLAY);
     /* See if we can get the desired overlay visual */
     if (!(pfChooseWinFBConfig(over, OverlayAttrs)))
         pfNotify(PFNFY_NOTICE, PFNFY_PRINT,
            “pfChooseWinFBConfig failed for OVERLAY win”);
     pfOpenWin(win);
     /* First select and draw into the overlay window */
     pfWinIndex(win, PFWIN_OVERLAY_WIN);
     /* Select causes the index to be applied */
     pfSelectWin(win); 
     ...
     /* Then select the main gfx window */
     pfWinIndex(win, PFWIN_GFX_WIN);
     pfSelectWin(win); 
     ...
}

Example 16-4 demonstrates the selection of X input events on a pfWindow. This example is taken from /usr/share/Performer/src/pguide/libpr/C/hlcube.c for IRIX and Linux and from %PFROOT%\Src\pguide\libpr\C\hlcube.c for Microsoft Windows.. See the /usr/share/Performer/src/pguide/libpf/C/complex.c sample program for a detailed example of using either standard or forked X input on pfWindows for IRIX and Linux and sample program %PFROOT%\Src\pguide\libpf\C\complex.c for Microsoft Windows.

    pfWSConnection Dsp;
 
void main (void)
{
    pfWindow *win;
    pfWSWindow xwin;
 
    /* Initialize Performer */
    pfInit();
    pfInitState(NULL);
 
    /* Initialize the window. */
     win = pfNewWin(NULL);
     pfWinOriginSize(win, 100, 100, 500, 500);
     pfWinName(win, “OpenGL Performer”);
     pfWinType(win, PFWIN_TYPE_X);
     pfOpenWin(win);
     ...
     /* set up X input event handling on pfWindow */
     Dsp = pfGetCurWSConnection();
     xwin = pfGetWinWSWindow(win);
     XSelectInput(Dsp, xwin, KeyPressMask );
     XMapWindow(Dsp, xwin);
     XSync(Dsp,FALSE);
     ...
     do_events(win);
}
static void 
do_events(pfWindow *win)
{
    while (1) {
    while (XPending(dsp))
    {
         XEvent event;
         XNextEvent(Dsp, &event);
         switch (event.type) 
         {
         case KeyPress:
          ....
          }
     }
}