In most cases, there are some window parameters, such as size and origin, that you will want to set. You may also have custom graphics state that you need to set to fully initialize your rendering window. This section describes the basics for setting up windows through the pfPipeWindow mechanism.

A pfPipeWindow can be created for a pfPipe using pfNewPWin(pipe). If you create a pfPipeWindow, then you are responsible for explicitly opening it. The call to pfOpenPWin(pwin) from the application process causes the next call to pfFrame() to trigger the opening of the pfPipeWindow in the draw process. A pfPipeWindow created in the application will be a rubber-band window of undefined size for the user to stretch out. This is in contrast to the full screen window that OpenGL Performer creates on your behalf in the fully automatic case. To easily get a full screen window, you can use the pfPWinFullScreen() function. pfPWinOriginSize() can be used to set a fixed position and size for the window. The code in Example 17-1, placed in the application process, creates and opens a window in the lower-left corner of the screen of size 500 pixels on each side.

main() 
{
    pfPipe *pipe;
    pfPipeWindow *pwin;
    pfInit();
    ....
    pfConfig();
    /* Create pfPipeWindow for pfPipe 0 */
    pipe = pfGetPipe(0;
    pwin = pfNewPWin(pipe);
    /* Set the origin and size of the pfPipeWindow */
    pfPWinOriginSize(pwin, 0, 0, 500, 500);
    /* Tell OpenGL Performer that the pfPipeWindow is ready to
     * be opened 
     */
    pfOpenPWin(pwin);
    /* trigger the opening of the pfPipeWindow 
     * in the draw process 
     */
    pfFrame();
    ...
    while(!SimDone())
    { ... }
}

The pfPipeWindow is always physically opened in the draw process when processing the application frame that requested the window to be opened. When both the cull and draw processes are running as separate processes, there might be a 2-frame delay (two additional calls to pfFrame()) for the window do actually be opened. Additionally, if the draw is running as a separate process, the window will not be opened right after pfFrame but some time in that following frame. If the pfPhase is such that the application process is allowed to spin ahead while the draw process does expensive initialization (anything but PFPHASE_FREE_RUN), the application process may execute many pfFrame() calls before the window is physically opened in the draw process. If in the application process you need to check on a result from opening the window, such as framebuffer configuration, you will want to do something that is in effect equivalent to the following:

while (!pfIsPWinOpen(pwin)) pfFrame();

pfPipeWindows are actually built upon libpr pfWindows, but have added support for handling the multiprocessed environment of libpf applications and fit into the libpf display hierarchy of pfPipes, pfPipeWindows, and pfChannels. Additionally, pfPipeWindows support the multiprocessing environment of libpf by having a separate copy of each pfPipeWindow in each pipeline process. All of the “windowness” of pfPipeWindows really comes from the fact that there is a pfWindow internal to the pfPipeWindow. Many of the basic support routines, such pfPWinFullScreen() and pfWinFullScreen(), have very similar functionality for pfWindows and pfPipeWindows. However, there are situations where pfPipeWindows are able to provide the same functionality in a much more efficient manner. Management of dynamic window origin and size is one case where pfPipeWindows have a real advantage over pfWindows. pfPipeWindows are able to take advantage of the multiprocessed libpf environment to always be able to return an accurate window size and origin relative to the window parent. A process separate from the rendering process is notified by the window system of changes in the pfPipeWindow's size in an efficient manner without impacting the window system or the rendering process. This can be forced off for the real-time static displays of a deployed visual simulation system by making the pfPipeWindow of type PFPWIN_TYPE_NOXEVENTS, which prevents OpenGL Performer from tracking the window. Further details regarding basic window creation and configuration are discussed with pfWindows in Chapter 16, “Windows”.

---

Note: pfPWin*() routines expect a pfPipeWindow and the pfWin*() routines a pfWindow. These routines are not interchangeable: pfWindow routines cannot accept pfPipeWindows nor the reverse. The PFWIN_* tokens can be used with the pfPipeWindow routines.

---

Windows have some intrinsic type attributes that must be set before the window is opened. The selection of the screen of a window is determined by the pfPipe that it is opened on, set for both the pfWindow and its pfPipe with the call pfPWinScreen(), or else set by the value of the DISPLAY variable when the window is finally opened. The window system configuration of the window must also be set before the window is opened. Windows under OpenGL operation on IRIX and Linux systems will always be X windows. On Microsoft Windows, the windows will be HWNDs.

---

Note: Micrsoft Wndows virtualizes the concept of a screen as well as all available hardware. Hence, on such systems, you cannot specify the screen connection in a manner similar to using the DISPLAY environment variable.

---

An open window must be closed for its type to be changed. The window type argument is actually a bitmask and the type of a pfPipeWindow can include the attributes listed in Table 17-1.

pfPipeWindows have a target default framebuffer configuration. The ability to meet this target depends on the current graphics hardware configuration, as well as their type. The following parameters are part of the target default configuration and are listed in their order of priority. If the goal framebuffer configuration cannot be created on the current graphics hardware configuration, lower priority parameters are downgraded as specified in the following:

pfPipeWindows have OpenGL Performer libpr rendering state automatically initialized when they are opened. Additionally the following graphics state is automatically initialized when a window is opened or upon any call to pfInitGfx() for an open window:

Custom framebuffer configuration for a pfPipeWindow can be specified with pfPWinFBConfigAttrs(), pfPWinFBConfig(), and pfChoosePWinFBConfig(). These routines have identical functionality as each of the corresponding pfWindow routines. However, the function pfChoosePWinFBConfig() has the constraint that it be called in the draw process because it creates and stores internal data from the window server that must be kept local to the process in which it is called. Table 17-2 lists the different pfPipeWindow routines and describes multiprocessing constraints.

The flexibility in changing the framebuffer configuration of OpenGL/X windows or OpenGL/HWNDs is complex. The main window can remain in place but structures under it must be switched or replaced. If multiple framebuffer configurations are likely to be desired, multiple graphics contexts can be created for the window using pfWindows. pfPipeWindows and pfWindows both allow you to have a list of alternate pfWindows that render to exactly the same screen area but may have different framebuffer configuration. You then select the current configuration for a pfPipeWindow with pfPWinIndex(). There are two kinds of common alternate configuration windows that can be created automatically for you: overlay windows created in the overlay planes and windows to support hardware fill statistics (discussed in Chapter 23, “Statistics”). You can use pfPWinMode() to indicate that you would like these windows created for you automatically. Special tokens to pfPWinIndex() are used to select these common special alternate configuration windows— PFWIN_GFX_WIN, PFWIN_OVERLAY_WIN and PFWIN_STATS_WIN—where PFWIN_GFX_WIN selects the normal default drawing window. Note that only a pfWindow, never a pfPipeWindow, can be an alternate configuration window. The source code in Example 17-2 is taken from /usr/share/Performer/src/pguide/libpf/C/pipewin.c for IRIX and Linux and from %PFROOT%\Src\pguide\libpf\C\pipewin.c for Microsoft Windows. It demonstrates the automatic creation and selection of overlay and statistics windows for a pfPipeWindow. This also shows usage of pfChannels and interaction between pfPipeWindows and pfChannels discussed in the section “Creating and Configuring a pfChannel” in Chapter 2.

main() 
{
    pfPipe *pipe;
    pfPipeWindow *pwin;
    pfInit();
    ....
    pfConfig();
 
    /* Create pfPipeWindow for pfPipe 0 */
    pipe = pfGetPipe(0);
    pwin = pfNewPWin(pipe);
    /* request automatic default overlay and stats windows */
    pfPWinMode(pwin, PFWIN_HAS_OVERLAY, PF_ON);
    pfPWinMode(pwin, PFWIN_HAS_STATS, PF_ON);
    /* Open the main graphics window */
    pfOpenPWin(pwin);
    pfFrame();
 
    while(!SimDone())
    {
    ...
    if (Shared->winSel == PFWIN_STATS_WIN))
    {
        /* select statistics window and enable fill stats */
        pfPWinIndex(Shared->pw, PFWIN_STATS_WIN);
        pfFStatsClass(fstats, 
              PFSTATSHW_ENGFXPIPE_FILL, PFSTATS_ON);
        pfEnableStatsHw(PFSTATSHW_ENGFXPIPE_FILL);
     }
     else
    {
        /* we are not doing statistics so turn them off */
        pfFStatsClass(fstats, 
            PFSTATSHW_ENGFXPIPE_FILL, PFSTATS_OFF);
        pfDisableStatsHw(PFSTATSHW_ENGFXPIPE_FILL);
        pfPWinIndex(Shared->pw, Shared->winSel);
    ...
    }
}
 
/* Channel draw process drawing function */
void DrawFunc(void pfChannel *chan)
{
    pfPipeWindow *pwin;
    pwin = pfGetChanPWin(chan);
    if (pfGetPWinIndex(pwin) == PFWIN_OVERLAY_WIN)
    {
        /* Draw overlay image */
        DrawOverlay();
        /* Put back the normal drawing window */
        pfPWinIndex(pwin, PFWIN_GFX_WIN);
        /* Indicate that we will now draw to the window */
        pfSelectPWin(pwin);
     }
     /* call the main OpenGL Performer drawing function */
     pfDraw();
}

Notice that in Example 17-2, although the pfPipeWindow is double buffered, the front and back color buffers are never explicitly swapped. For pfPipeWindows, this operation is done automatically after all channels on the parent pfPipe have completed their drawing for the given frame. The color buffers of a pfPipeWindow may be swapped explicitly with pfSwapWinBuffers. This call may be placed in a user-swap function call back placed on the pfPipe with pfPipeSwapFunc() to replace the pfPipe normal swap behavior. The swap callback will be called in the draw process at the end of the frame after all pfChannels in all pfWindows have been drawn for the pfPipe. The function is called for all of the pfPipeWindows on the pfPipe. This is additionally useful for doing end-of-frame rendering or readbacks from the framebuffer.

You may need to set additional window and graphics state to complete the initialization of your pfPipeWindow. Calling pfOpenPWin() from the application process does not give you the opportunity to do this. However, with pfPWinConfigFunc(), you can supply a window configuration callback function that will enable you to open and initialize your pfPipeWindow in the draw process. A call to pfConfigPWin() triggers one call of the window configuration callback in the draw process upon the next call to pfFrame(). pfConfigPWin() can be called at any time to trigger the calling of the current window configuration function in the draw process. Example 17-3 demonstrates initializing a pfPipeWindow from a draw process window configuration callback. It creates a global light to serve as the Sun in the window configuration callback. (see the /usr/share/Performer/src/pguide/libpf/C/complex.c example for IRIX and Linux and %PFROOT%\Src\pguide\libpf\C\complex.c for Microsoft Windows).

main() 
{
    pfPipe *pipe;
    pfPipeWindow *pwin;
    pfInit();
    ....
    pfConfig();
 
    /* Create pfPipeWindow for pfPipe 0 */
    pipe = pfGetPipe(0);
    pwin = pfNewPWin(pipe);
    /* Set the configuration function for the pfPipeWindow */
    pfPWinConfigFunc(pwin, OpenPipeWindow);
    /* Indicate that OpenPipeWindow should be called in the 
     * draw process.
     */
    pfConfigPWin(pwin);
 
    /* trigger OpenPipeWindow to be called in the draw process */
    pfFrame();
    while(!SimDone())
    { ... }
}
 
/* Initialize graphics state in the draw process */
void
OpenPipeWindow(pfPipeWindow *pw)
{
    /* Set some configuration stuff */
    pfPWinOriginSize(pw, 0, 0, 500, 500);
    /* Open the window - will give us initialized libpr and      *     graphics state 
     */
    pfOpenPWin(pw);
    
    /* create a global light in the “south-west” (QIII) */
    Sun = pfNewLight(NULL);
    pfLightPos(Sun, -0.3f, -0.3f, 1.0f, 0.0f);
}

In Example 17-3 the functions pfPWinOriginSize() and pfOpenPWin() are now called in the draw process, as opposed to the application process as in Example 17-1. In general, configuring or editing any libpf object must be done in the application process. pfPipeWindows must be created in the application process. However, pfPipeWindows may be configured, edited, opened and closed in the pfPWinConfigFunc() configuration callback which will be called in the draw process. Window operations are best done in a configuration callback, though they can also be done in the drawing callback for a pfChannel on the window. Any function which aspires to directly affect the graphics context must be called in the drawing process. Table 17-2 shows which processes (application or draw via a configuration function) that pfPipeWindow calls can be made from and further detail about these functions can be found in the discussion of pfWindows in Chapter 16, “Windows”.

OpenGL Performer provides GL-independent framebuffer configuration utilities. In most cases, pfPWinFBConfigAttrs(pwin, attrs) can be used to select a framebuffer configuration for your pfPipeWindow based on the array of attribute tokens attrs. If attrs is NULL, the default framebuffer configuration will be selected. If attrs is not NULL, the rules for default values follow the rules for configuring windows in OpenGL and X, which are different from values in the OpenGL Performer default window configuration. Such window framebuffer configuration should be done in the draw process in a window configuration callback function before the call to pfOpenPWin(). Window framebuffer configuration for pfPipeWindows is identical to that of pfWindows and is discussed in more detail in Chapter 16, “Windows”, but the following is a simple example of the specification of framebuffer configuration taken from the sample source code example program /usr/share/Performer/src/pguide/libpf/C/pipewin.c for IRIX and Linux and from %PFROOT%\Src\pguide\libpf\C\pipewin.c for Microsoft Windows:

static int FBAttrs[] = {
    PFFB_RGBA,
    PFFB_DOUBLEBUFFER,
    PFFB_DEPTH_SIZE, 24,
    PFFB_RED_SIZE, 8,
    PFFB_SAMPLES, 8,
    PFFB_STENCIL_SIZE, 1,
    NULL,
};
 
main() 
{
    pfPipe *pipe;
    pfPipeWindow *pwin;
    pfInit();
    ....
    pfConfig();
 
    /* Create pfPipeWindow for pfPipe 0 */
    pipe = pfGetPipe(0);
    pwin = pfNewPWin(pipe);
    /* Set the framebuffer configuration */
    pfPWinFBConfigAttrs(Shared->pw, FBAttrs);
    /* Indicate that the window is ready to open */
    pfOpenPWin(pwin);
    /* trigger the opening of the window in the draw */
    pfFrame();
    ...
}

If you want to do all of your own window creation and management you can do so and just give OpenGL Performer the handles to your windows with the pfPWinWSDrawable() function; you may also provide a parent X window (or HWND on Microsoft Windows) with the pfPWinWSWindow() function. pfOpenPWin() makes use of any windows that have already been provided. More details regarding the creation and configuration of pfPipeWindows and pfWindows are discussed in Chapter 16, “Windows”.

pfPipeWindows allow for a reasonable amount of flexibility in the running application. pfPipeWindows can be re-ordered on their parent pfPipe to control the order that they are drawn in with the command pfMovePWin(pipe, index, pwin). pfPipeWindows can be dynamically opened and closed in the application or draw processes with pfOpenPWin() and pfClosePWin(). Additionally, pfConfigPWin() can be re-issued at any time from the application process to call the current window configuration function to dynamically open, close, and reconfigure pfPipeWindows.

The following example is taken from the distributed source code example file /usr/share/Performer/src/pguide/libpf/C/pipewin.c for IRIX and Linux and from %PFROOT%\Src\pguide\libpf\C\pipewin.c for Microsoft Windows. It demonstrates the dynamic closing of a window from the application process in the simulation loop and the reuse of pfConfigPWin() to reopen the window.

main()
{
    ...
    /* main simulation loop */
    while (!Shared->exitFlag)
    {
    /* wait until next frame boundary */
    pfSync();
    pfFrame();
    /* Set view parameters for next frame */
    UpdateView();
    pfChanView(chan, Shared->view.xyz, Shared->view.hpr);
 
    /* Close pfPipeWindow */
    if (Shared->closeWin == 1)
    {
        pfClosePWin(Shared->pw);
        ct = pfGetTime();
        Shared->closeWin = 2;
    } 
    /* then wait two seconds and reconfig window */
    else if ((Shared->closeWin == 2) && 
                        (pfGetTime() - ct > 2.0f))
    {
       pfConfigPWin(Shared->pw);
       Shared->closeWin = 3;
       pfNotify(PFNFY_NOTICE, PFNFY_PRINT, “OPEN”);
}   }
    ...
}

You create a pfPipeVideoChannel from a pfPipe using pfNewPVChan() and providing the parent pfPipe. The pfPipeVideoChannel is then attached to a pfPipeWindow with pfAddPWinPVChan(), which returns an index into the pfPipeWindow's video channel list. Additionally, if the pfPipeVideoChannel has not already been assigned a hardware video channel with pfPVChanId(), the next active video channel will be assigned.

pfPipe *p = pfGetPipe(0);
pfPipeVideoChannel *pvc = pfNewPVChan(p);
pfPVChanId(pvc,0);
pvcIndex = pfPWinAddPVChan(pwin, pvc);

To find out if a pfPipeVideoChannel with its current video channel assignment is active for displaying output, call pfIsPVChanActive(), which returns 0 if the video channel assignment is not fully defined or if the channel is not active and returns 1 otherwise. The assignment of a hardware video channel is not complete until the screen of the pfPipe is known and so might not be done immediately if the pfPipe screen has not been set with pfPipeScreen() or if the pfPipeWindow is not open. Even if you have explicitly assigned a hardware video channel ID, it is only meaningful relative to a known screen. The hardware video channel assignment can be changed at any time with pfPVChanId(). It is an error to have multiple pfPipeWindows and pfPipeVideoChannels attempt to manage the same hardware video channel. The index returned by pfAddPWinPVChan() is then used for a pfChannel to reference this pfPipeVideoChannel. pfPipeWindows always have an initial pfPipeVideoChannel already attached whose default video channel will be the first active video channel on the screen of the pfPipe. So, only add pfPipeVideoChannels if you actually need additional video channels.

The only video channels a pfPipeVideoChannel can manage are those of the screen of the pfPipe. Use pfGetNumScreenPVChans() to find out how many active video channels are on a given screen.

To add additional pfPipeVideoChannels to a single pfPipeWindow, use pfPWinAddPVChan(). The routine returns an index number associated with the pfPipeWindow, or -1 if an error occurs. If the pfPipeVideoChannel does not already have an assigned hardware video channel, the next active video channel relative to the video channels already attached to the pfPipeWindow will be assigned.

There are list routines to manage the list of pfPipeVideoChannels on a pfPipeWindow. Use pfGetPWinNumPVChans() to find out how many pfPipeVideoChannels are being managed by the pfPipeWindow. pfPWinRemovePVChan() and pfPWinRemovePVChanIndex() disassociate a pfPipeVideoChannel from a pfPipeWindow, using either the pfPipeWindow object or an index number to specify the pfPipeWindow.

There are additional utilities to find pfPipeVideoChannels on pfPipeWindows. You can obtain the index value of a pfPipeVideoChannel for a pfPipeWindow using pfGetPWinPVChanIndex(), which returns the index of a pfPipeVideoChannel, or -1 of the pfPipeVideoChannel is not registered with the pfPipeWindow. Use pfGetPWinPVChanId() to find a pfPipeVideoChannel on a pfPipeWindow with the specified hardware Id. NULL will be returned if no such pfPipeVideoChannel exists on the specified pfPipeWindow.

pfPipeVideoChannels are bound to their hardware video channels in a lazy fashion as needed by configuration requests. Basic queries of a video channel do not require any explicit binding. Changing a video channel's properties does require explicit binding. pfPipeWindows manage this process. However, explicit binding and unbinding might be necessary if changes are made to video channels directly through the XSGIvc API and not through the pfPipeVideoChannel API. This is quite reasonable since pfPipeVideoChannels do not duplicate all of XSGIvc. A pfPipeVideoChannel is bound to its hardware video channel with pfBindPVChan(). All of the pfPipeVideoChannels associated with a pfPipeWindow can be bound in one step with pfBindPWinPVChans() and unbound with pfUnbindPWinPVChans(). You can get the XSGIvc handle from a pfPipeVideoChannel to do your own configuration or extended queries with pfGetPVChanInfo().

There are two mechanisms by which pfPipeVideoChannels can help you maintain constant frame rate in your application. Dynamic Video Resolution (DVR) addresses reducing load caused by filling to many pixels. Pan/Zoom video scan-out to sample different parts of the frame buffer, under resize, to be selected asynchronously to a draw process. Both of these mechanisms make use of editing the size and or origin of the output area of a pfPipeVideoChannel, supported by InfiniteReality graphics platforms. Using pfPVChanOutputSize() and pfPVChanOutputAreaScale() changes the output area size of the bound video channel. pfPVChanOutputOrigin() changes the origin of the output area. The pfPipeVideoChannel(3) references more routines to manage video channel origin and size.

On InfiniteReality graphics platforms, you can use pfPipeVideoChannels to dynamically adjust the size of the output area of the video channel. The output area is then automatically zoomed up to full video channel size by the InfiniteReality hardware using bilinear filtering. This operation has no added performance cost or latency. This feature can be used to allow pfChannels to reduce their viewport size to the reduced video channel output area. Reducing the number of pixels drawn reduces the fill load for the pfPipe and can be used as a load management technique for maintaining constant frame rates. pfPipeVideoChannels support manual resizing, allowing you to implement your own load management, or automatically resizes the output area and the pfChannel viewports. You can enable and select a resizing mode with pfPVChanDVRMode() and providing PFPVC_DVR_MANUAL or PFPVC_DVR_AUTO. The default value is PFPVC_DVR_OFF. For more information, see “Level-of-Detail Management” in Chapter 5.

pfPipeVideoChannels also support asynchronous editing of their size and origin. This can be used in an asynchronous process, or in an application process that is reliably running at frame rate, to edit the origin and size of the video channel. These changes will affect the following video field if the pfPVChanMode() for PFVCHAN_AUTO_APPLY is set to 1 (default is 0) and the PFVCHAN_SYNC mode is set to PFVCHAN_SYNC_FIELD (default is PFVCHAN_SYNC_FRAME which selects apply upon swapbuffers).

Real-time changes to pfPipeVideoChannel origin or size should be done between pfSync() and pfFrame() to affect the next draw frame or video field.