OpenGL Performer is designed to run at the fixed frame rate as specified by pfFrameRate(). Selecting a fixed frame rate does not in itself guarantee that each frame can be completed within the desired time. It is possible that some frames might require more computation time than is allotted by the frame rate. By taking too long, these frames cause dropped or skipped frames. A situation in which frames are dropped is called an overload or overrun situation. A system that is close to dropping frames is said to be in stress.

The first step towards achieving a frame rate is to make sure that the scene can be processed in less than a frame's time—hopefully much less than a frame's time. Although minimizing the processing time of a frame is a huge effort, rife with tricks and black magic, certain techniques stand out as OpenGL Performer's main weapons against slothful performance:

Multiprocessing and level-of-detail is discussed in this chapter while view culling and state sorting are discussed in Chapter 4, “Database Traversal”. More information on sorting in the context of performance tuning can be found in Chapter 24, “Performance Tuning and Debugging”. 

Frame intervals are fixed periods of time but frame processing is variable in nature. Because things change in a scene, such as when objects come into the field of view, frame processing cannot be fixed. In order to maintain a fixed frame rate, the average frame processing time must be less than the frame time so that fluctuations do not exceed the selected frame rate. Alternately, the scene complexity can be automatically reduced or increased so that the frame rate stays within a user-defined “sweet spot.” This mechanism requires that the scene be modeled with levels of detail (pfLOD nodes).

OpenGL Performer calculates the system load for each frame. Load is calculated as the percentage of the frame period it took to process the frame. Then if the default OpenGL Performer fixed frame rate mechanisms are enabled, load is used to calculate system stress, which is in turn used to adjust the level of detail (LOD) of visible models. LOD management is OpenGL Performer's primary method of managing system load.

Table 5-1 shows the OpenGL Performer functions for controlling frame processing.

Figure 5-1 shows a frame-timing diagram that illustrates what occurs when frame computations are not completed within the required interval. The solid vertical lines in Figure 5-1 represent frame-display intervals. The dashed vertical lines represent video refresh intervals.

Figure 5-1. Frame Rate and Phase Control

In this example, the video scan rate is 60 Hz and the frame rate is 20 Hz. With the video hardware running at 60 Hz, each of the 20 Hz frames should be scanned to the video display three times, and the system should wait for every third vertical retrace signal before displaying the next image. The numbers across the top of the figure represent the refresh count modulo three. New images are displayed on refreshes whose count modulo three is zero, as shown by the solid lines.

In the first frame of this example, the new image is not yet completed when the third vertical retrace signal occurs; therefore, the same image must be displayed again during the next interval. This situation is known as frame overrun, because the frame computation time extends past a refresh boundary.

pfPhase(PFPHASE_LOCK);
pfFrameRate(20.0f);

/* Set the desired frame rate. */
pfFrameRate(ViewState->frameRate);
 
/* Set the MP synchronization phase. */
pfPhase(ViewState->phase);
 
/* Application main loop */
while (!SimDone())
{
    /* Sleep until next frame */
    pfSync();
 
    /* Should do all latency-critical processing between
     * pfSync() and pfFrame().  Such processing usually
     * involves changing the viewing position.
     */
    PreFrame();
 
    /* Trigger cull and draw processing for this frame. */
    pfFrame();
 
    /* Perform non-latency-critical simulation updates. */
    PostFrame();
}

Most objects comprise smaller objects that become visually insignificant at ranges where the conglomerate object itself is still quite prominent. For example, a complex model of an automobile might have door handles, side- and rear-view mirrors, license plates, and other small details.

A short distance away, these features may no longer be visible, even though the car itself is still a visually significant element of the scene. It is important to realize that as a group, these small features may contain as many polygons as the larger car itself, and thus have a detrimental effect on rendering speed.

You can construct two LOD models simply by providing one model that contains all of the detailed features and another model that contains only the car body itself and none of the detailed features. A more sophisticated scheme uses multiple LOD models that are grouped under an LOD node.

Figure 5-2 shows an LOD node with multiple children numbered 1 through n. In this case, the model named LOD 1 is the most detailed model and models LOD 2 through LOD n represent progressively coarser models. Each of these LOD models might contain children that also have LOD components. Associated with the LOD node is a list of ranges that define the distance at which each model is appropriate to display. There is no limit to the number of levels of detail that can be used.

Figure 5-2. Level-of-Detail Node Structure

The object can be transformed as needed. During the culling phase of frame processing, the distance from the eyepoint to the object is computed and used (with other factors) to select which LOD model to display.

The OpenGL Performer pfLOD node contains a value known as the center of LOD processing. The LOD center point is an x, y, z location that defines the point used in conjunction with the eyepoint for LOD range-switching calculations, as described in the section “Level-of-Detail Range Processing” of this chapter.

Figure 5-3 shows an example in which multiple LOD models grouped under a parent LOD node are used to represent a toy race car.

Figure 5-3. Level-of-Detail Processing

Figure 5-3 demonstrates that each car in a row of identical cars placed at increasing range from the eyepoint is drawn using a different child of the tree's LOD node.

The double-ended arrows indicate a switch range for each level of detail. When the car is closer to the eyepoint than the first range, nothing is drawn. When the car is between the first and second ranges, LOD 1 is drawn. When the car is between the second and third ranges, LOD 2 is drawn.

This range bracketing continues until the final range is passed, at which point nothing is drawn. The pfLOD node's switch range list contains one more entry than the number of child nodes to allow for this range bracketing.

OpenGL Performer provides the ability to specify a blend zone for each switch between LOD models. These blend zones will be discussed in more detail in “Level-of-Detail Transition Blending”.

In addition to standard LOD nodes, OpenGL Performer also supports LOD state—the pfLODState. A pfLODState is in essence a way of creating classes or priorities among LODs. A pfLODState contains eight parameters used to modify four different ways in which OpenGL Performer calculates LOD switch ranges and LOD transition distances. LOD states contain the following parameters:

These LOD states can then be attached to either single or multiple LOD nodes such that the LOD behavior of groups or classes of objects can be different and be easily modified. The man pages for pfLODLODState() and pfLODLODStateIndex() contain detailed information on how to attach pfLODStates.

LOD states are useful because in a particular scene there often exists an object of focus such as a sign, a target, or some other object of particular visual significance that needs to be treated specially with regard to visual importance and thus LOD behavior. It stands to reason that this particular object (or small group of objects) should be at the highest detail possible despite being farther away than other elements in the scene which might not be as visually significant. In fact, it might be feasible to diminish the detail of less important objects (like rocks and trees) in favor of the other more important objects (despite these objects being more distant). In this case one would create two LOD states. The first would be for the important objects and could disable the effect of stress on these nodes as well as scale the switch ranges such that the object(s) would maintain more detail for further ranges. The second LOD state would be used to make the objects of less importance be more responsive to system stress and possibly scale their switch ranges such that they would show even less detail than normal. In this way, LOD states allow biasing among different LODs to maintain desirable rendering speeds while maintaining the visual integrity of various objects depending on their subjective importance (rather than solely on their current visual significance).

In some multichannel applications, LOD states are used to control the action of LODs in different viewing channels that have different visual significance criteria—for instance one channel might be a normal channel while a second might represent an infrared display. Rather than simple use of LOD states, it is also possible to specify a list of LOD states to a channel and use indexes from this list for particular LODs (with pfChanLODStateList() and pfLODLODStateIndex()). In this way, in the normal channel a car's geometry might be particularly important while in the infrared channel, the hot exhaust of the same car might be much more important to observe. This type of channel-dependent LOD can be set up by using two distinct and different LOD states for the same index in the lists of LOD states specified for unique channels.

Note that because OpenGL Performer performs LOD calculations in a range squared space as much as possible for efficiency reasons, LOD computation becomes more costly when LOD states contain scales that are not equal to 1.0 or offsets not equal to 0.0 for transitions or switch ranges—these offsets force OpenGL Performer to perform otherwise avoidable square root calculations in order to correctly calculate the effects of scale and offset on the LOD.

The LOD switch ranges present in LOD nodes are processed before being used to make the level of detail selection. The goal of range setting is to switch LODs as objects reach certain levels of perceptibility. The size of a channel in pixels, the field of view used in viewing, and the distance from the observer to the display surface all affect object perceptibility.

OpenGL Performer uses a channel size of 1024x1024 pixels and a 45-degree field of view as the basis for calculating LOD switching ranges. The screen space size of a channel and the current field of view are used to compute an LOD scale factor that is updated whenever the channel size or the field of view changes.

There is an additional global LOD scale factor that can be used to adjust switch ranges based on the relationship between the observer and the display surface. The default global scale factor is 1.

Note that LOD switch ranges are also affected by LOD states that have been attached to either a particular LOD or to a channel that contains the LOD. These LOD states provide the mechanism to apply both a scale and an offset for an LODs switch ranges and to the effect of system stress on those switch ranges. See “Level-of-Detail States” for more information on pfLODStates.

Ultimately, an LOD's switch range without regard to system stress can be computed as follows:

    switch_range[i] = 
        (range[i] * 
            LODStateRangeScale *
            ChannelLODStateRangeScale +
            LODStateRangeOffset +
            ChannelLODStateRangeOffset) *
        ChannelLODScale *
        ChannelSizeAndFOVFactor;

If OpenGL Performer channel stress processing is active, the computed range is modified as follows:

    switch_range[i] *=
        (ChannelLODStress *
        LODStateRangeStressScale *
        ChannelLODStateRangeStressScale +
        LODStateRangeStressOffset +
        ChannelLODStateRangeStressOffset);

Example 5-2 illustrates how to set LOD ranges.

/* setLODRanges() -- sets the ranges for the LOD node. The
 * ranges from 0 to NumLODs are equally spaced between min
 * and max.  The last range, which determines how far you
 * can get from the object and still see it, is set to
 * visMax.
 */
void
setLODRanges(pfLOD *lod, float min, float max, float visMax)
{
    int i;
    float range, rangeInc;
 
    rangeInc = (max - min)/(ViewState->shellLOD + 1);
    for (range = min, i = 0; i < ViewState->shellLOD; i++)
    {
        ViewState->range[i] = range;
        pfLODRange(lod, i, range);
        range += rangeInc;
    }
    ViewState->range[i] = visMax;
    pfLODRange(lod, i, visMax);
}
 
/* generateShellLODs() -- creates shell LOD nodes according
 * to the parameters specified in the shared data structure.
 */
void
generateShellLODs(void)
{
    int i;
    pfGroup *grp;
    pfVec4 clr;
    long numLOD = ViewState->shellLOD;
    long numPnts = ViewState->shellPnts;
    long numPcs = ViewState->shellPcs;
 
    for (i = 1; i <= numLOD; i++)
    {
        if (ViewState->shellColor == SHELL_COLOR_SING)
            pfSetVec4(clr, 0.9f, 0.1f, 0.1f, 1.0f);
        else
            /* set the color.  highest level = RED;
             * middle LOD = GREEN; lowest LOD = BLUE
             */
            pfSetVec4(clr,
                  (i <= (long)floor((double)(numLOD/2.0f)))?
                     (-2.0f/numLOD) * i + 1.0f + 2.0f/numLOD:
                     0.0f,
                  (i <= (long)floor((double)(numLOD/2)))?
                     (2.0f/numLOD) * (i - 1):
                     (-2.0f/numLOD) * i + 2.0f,
                  (i <= (long)floor((double)(numLOD/2)))?
                     0.0f:
                     (2.0f/numLOD) * i - 1.0f,
                  1.0f);
 
        /* build a shell GeoSet */
        grp = createShell(numPcs, numPnts,
                          ViewState->shellSweep, &clr,
                          ViewState->shellDraw);
        normalizeNode((pfNode *)grp);
 
        /* add geode as another level of detail node */
        pfAddChild(ViewState->LOD, grp);
 
        /* simplify the geometry, but don't have less than
         * 4 points per circle or less than 3 pieces */
        numPnts = (numPnts > 7) ? numPnts-4 : 4;
        numPcs = (numPcs > 6) ? numPcs-4 : 3;
    }
}
 
...
    ViewState->LOD = pfNewLOD();
 
    generateShellLODs();
 
    /* get the LOD's extents */
    pfGetNodeBSphere(ViewState->LOD, &(ViewState->bSphere));
    pfLODCenter(ViewState->LOD, ViewState->bSphere.center);
    /* set ranges for LODs; there should be (num LODs + 1)
     * range entries */
    setLODRanges(ViewState->LOD, ViewState->minRange,
                 ViewState->maxRange, ViewState->max);

An undesirable effect called popping occurs when the sudden transition from one LOD to the next LOD is visually noticeable. This distracting image artifact can be ameliorated with a slight modification to the normal LOD-switching process.

In this modified method, a transition per LOD switch is established rather than making a sudden substitution of models at the indicated switch range. These transitions specify distances over which to blend between the previous and next LOD. These zones are considered to be centered at the specified LOD switch distance, as shown by the horizontal shaded bars of Figure 5-3. Note that OpenGL Performer limits the transition distances to be equal to the shortest distance between the switch range and the two neighboring switch ranges. For more information, see the pfLODTransition() man page.

As the range from eyepoint to LOD center-point transitions the blend zone, each of the neighboring LOD levels is drawn by using transparency-to-composite samples taken from the present LOD model with samples taken from the next LOD model. For example, at the near, center, and far points of the transition blend zone between LOD 1 and LOD 2, samples from both LOD 1 and LOD 2 are composited until the end of the transition zone is reached, where all the samples are obtained from LOD 2.

Table 5-2 lists the transparency factors used for transitioning from one LOD range to another LOD range.

LOD transitions are made smoother and much less noticeable by applying a blending technique rather than making a sudden transition. Blending allows LOD transitions to look good at ranges closer to the eye than LOD popping allows. Decreasing switch ranges in this way improves the ability of LOD processing to maximize the visual impact of each polygon in the scene without creating distracting visual artifacts.

The benefits of smooth LOD transition have an associated cost. The expense lies in the fact that when an object is within a blend zone, two versions of that object are drawn. This causes blended LOD transitions to increase the scene polygon complexity during the time of transition. For this reason, the blend zone is best kept to the shortest distance that avoids distracting LOD-popping artifacts. Currently, fade level of detail is supported only on RealityEngine and InfiniteReality graphics systems.

Note that the actual `blend' or `fade' distance used by OpenGL Performer can also be adjusted by the LOD priority structures called pfLODStates. pfLODStates hold an offset and scale for the size of transition zones as well as an offset and scale for how system stress can affect the size of the transition zones. See “Level-of-Detail States” for more information on pfLODStates.

Note also, that there exists a global LOD transition scale on a per channel basis that can affect all transition distances uniformly.

Thus for an LOD with 5 switch ranges R0, R1, R2, R3, R4 to switch between four models (M0, M1, M2, M3), there are 5 transition zones T0 (fade in M0), T1 (blend between M0 and M1), T2 (blend between M1 and M2), T3 (blend between M2 and M3), T4 (fade out M3). The actual fade distances (without regard to channel stress) are as follows:

    fadeDistance[i] = 
        (transition[i] * 
            LODStateTransitionScale * 
            ChannelLODStateTransitionScale +
            LODStateTransitionOffset +
            ChannelLODStateTransitionOffset) *
        ChannelLODFadeScale;

If OpenGL Performer management of channel stress is turned on then the above fade distance is modified as follows:

    fadeDistance[i] /= 
        (ChannelStress * 
        LODStateTransitionStressScale * 
        ChannelLODStateTransitionStressScale +
        LODStateTransitionStressOffset +
        ChannelLODStateTransitionStressOffset);

A pfLOD node provides one last resort for applications that have complex level-of-detail calculations. For example, an application might wish to limit the speed at which different LODs of an object switch. When switching depends on the range from the camera, a very fast-moving camera may result in rapid changes of LODs. The application may require an artificial filter to take the simple range-based evaluation and ease it into the display over time.

An application may take over the LOD evaluation function using the API pfLODUserEvalFunc() on pfLOD. The user-supplied function must return a floating point number. Similar to the result of pfEvaluateLOD(), this number picks either a single child or a blend of two children of the pfLOD node.

Note that the performance of the cull process may decrease if the user function is too slow to execute.

In creating LOD models and transitions for objects, it is often safe to assume that the entire model should transition at the same time. It is quite reasonable to make features of an automobile such as door handles disappear from the scene at the same time even when the passenger door is slightly closer than the driver's door. It is much less clear that this approach would work for very large objects such as an aircraft carrier or a space station, and it is clearly not acceptable for objects that span a large extent, such as a terrain surface.

When using Dynamic Video Resolution (DVR), the origin and size of a channel are dynamic. For example, a viewport whose lower-left corner is at the center of a pfPipe (with coordinates 0.5, 0.5) would be changed to an origin of (0.25, 0.25) with respect to the full pfPipe window if the DVR settings were scaled by a factors of 0.5 in both X and Y dimensions.

If you are doing additional rendering into a pfChannel, you may need to know the size and the actual rendered area of the pfChannel. Use pfGetChanOutputOrigin() and pfGetChanOutputSize() to get the actual rendered origin and size, respectively, of a pfChannel. pfGetChanOrigin() and pfGetChanSize() give the displayed origin and size of the pfChannel and these functions should be used for mapping mouse positions or other window-relative nonrendering positions to the pfChannel area.

Additionally, if DVR alters the rendered size of a pfChannel, a corresponding change should be made to the width of points and lines. For example, when a channel is scaled in size by one half, lines and points must be drawn half as wide as well so that when the final image is enlarged, in this case by a factor of two, the lines and points scale correctly. pfChanPixScale() sets the pixel scale factor. pfGetChanPixScale() returns this value for a channel. pfChannels set this pixel scale automatically.

DVR scales linearly in response to the most common cause of draw overload: filling the polygons. For example, if the DRAW stage process overran by 50%, to get back in under the frame time, the new scene must draw 30% fewer pixels. We can do this with DVR by rendering to a smaller viewport and letting the video hardware rescale the image to the correct display size.

If pfPVChanMode() is set to PFPVC_DVR_AUTO, OpenGL Performer automatically scales each of the pfChannels. pfChannels automatically scale themselves according to the scale set on the pfPipeVideoChannel they are using.

If the pfPVChanMode() is PFPVC_DVR_MANUAL, you control scaling according to your own policy by setting the scale and size of the pfPipeVideoChannel in the application process between pfSync() and pfFrame(), as shown in this example:

Total pixels drawn last frame = ChanOutX * ChanOutY * Depth Complexity

To make the total pixels drawn 30% less, do the following:

NewChanOutX = NewChanOutY = .7 * (Chan OutX * ChanOut.)
New ChanOut X = sqrt (.7) * ChanOutX
New ChanOut X = sqrt (.7) * ChanOut X
NewChanOut = sqrt (.7) * ChanOut

Your application has full control over DVR behavior. You can either configure the automatic mode or implement your own response control.

Automatic resizing can cause problems when an image has so much information in it the viewport is reduced too drastically, perhaps to only a few hundred pixels, so that when the image is enlarged, the image resolution is unacceptably blurry. To remedy this problem, pfPipeVideoChannel includes the following methods to limit the reduction of a video channel:

Each of these methods have corresponding Get methods that return the values set by these methods.

To resize the video channel manually, use pfPipeVideoChannel sizing methods, such as pfPVChanOutputSize(), pfPVChanAreaScale(), and pfPVChanScale().

The pfPipeVideoChannel associated with a channel is returned by pfGetChanPVChan(). If there is more than one pfPipeVideoChannel associated with a pfPipeWindow, each one is identified by an index number. In the case of multiple pfPipeVideoChannels, the pfPipeVideoChannel index is set using pfChanPWinPVChanIndex() and returned by pfGetChanPWinPVChanIndex().

The  pfPVChanStressFilter() function sets the parameters for computing stress for a pfPipeVideoChannel when the stress is not explicitly set for the current frame by pfPVChanStress(), as shown in the following example:

void pfPipeVideoChannel::setStressFilter(float *frameFrac,
     float *lowLoad, float *highLoad, float *pipeLoadScale,
     float *stressScale, float *maxStress);

The frameFrac argument is the fraction of a frame that pfPipeVideoChannel is expected to take to render the frame; for example, if the rendering time is equal to the period of the frame rate, frameFrac is 1.

If there is only one pfPipeVideoChannel, it is best if frameFrac is 1. If there are more than one pfPipeVideoChannels on the pfPipe, by default frameFrac is divided among the pfPipeVideoChannels. You can set frameFrac explicitly for each pfPipeVideoChannel such that a channel rendering visually complex scenes is allocated more time than a channel rendering simple scenes.

The  pfGetPFChanStressFilter() function returns the stress filter parameters for pfPipeVideoChannel. If stressScale is nonzero, stress is computed for the pfPipeVideoChannel every frame. The parameters low and high define a hysteresis band for system load. When the load is above lowLoad and below highLoad, stress is held constant. When the load falls outside of the lowLoad and highLoad parameters, OpenGL Performer reduces or increases stress respectively by dynamically resizing the output area of the pfPipeVideoChannel until the load stabilizes between lowLoad and highLoad.

If pipeStressScale is nonzero, the load of the pfPipe of the pfPipeVideoChannel are considered in computing the stress. The parameter maxStress is the clamping value above which the stress value cannot go. For more information about the stress filter, see the man page for pfPipeVideoChannel.

The OpenGL Performer application renders images using one or more pfPipes as independent software-rendering pipelines. The flow through the rendering pipeline can be modeled using these functional stages:

You can partition these stages into separate parallel processes in order to distribute the work among multiple CPUs. Depending on your system type and configuration, you can use any of several available multiprocessing models.

Use pfMultiprocess() to specify which functional stages, if any, should be forked into separate processes. The multiprocessing mode is actually a bitmask where each bit indicates that a particular stage should be configured as a separate process. For example, the bit PFMP_FORK_DRAW means the draw stage should be split into its own process. Table 5-3 lists some convenient tokens that represent common multiprocessing modes.

You can also use the pfMultiprocess() function to specify the method of communication between the cull and draw stages, using the bitmasks PFMP_CULLoDRAW and PFMP_CULL_DL_DRAW.

Comparative Structure of Models

Figure 5-6 shows timing diagrams for each of the process models. The vertical lines are frame boundaries. Five frames of the simulation are shown to allow the system to reach steady-state operation. Only one of these models can be selected at a time, but they are shown together so that you can compare their structures.

Boxes represent the functional stages and are labeled as follows:

An		Application process for the nth frame
Cn		Cull process for the nth frame
Dn		Draw process for the nth frame Figure 5-6. Multiprocessing Models

Notice that when a stage is split into its own process, the amount of time available for all stages increases. For example, in the case where the application, cull, and draw stages are three separate processes, it is possible for total system performance to be tripled over the single process configuration.

Many databases are too large to fit into main memory. A common solution to this problem is called database paging where the database is divided into manageable chunks on disk and loaded into main memory when needed. Usually chunks are paged in just before they come into view and are deleted from the scene when they are comfortably out of viewing range.

All this paging from disk and deleting from main memory takes a lot of time and is certainly not amenable to maintaining a fixed frame rate. The solution supported by OpenGL Performer is asynchronous database paging in which a process, completely separate from the main processing pipeline(s), handles all disk I/O and memory allocations and deletions. To facilitate asynchronous database paging, OpenGL Performer provides the pfBuffer structure and the DBASE process.

When placing multiple OpenGL Performer processes on the same CPU, some combinations of processes and priorities may have an effect on the APP process timing even if the APP process runs on its own separate CPU. This happens because the APP process often waits on other processes for completion of various tasks. If these other processes share a CPU with high-priority processes, they may take a long time to finish their task and release the APP process.

An application can request that OpenGL Performer upgrade the priority of processes when the APP process waits on them by calling pfProcessPriorityUpgrade(). The APP process upgrades the other process' priority before it starts waiting for it, and the other process resumes its previous priority as soon as it releases the APP process. In this way, the original settings of priorities is maintained, except when the APP process waits for another process. OpenGL Performer uses the priority 87 as the default priority for upgrading processes. This priority is the default because it is close to the highest priority that any application-level process should ever have (89). The application may change this priority by using pfProcessHighestPriority().

The priority-upgrade mode is turned off by default. An OpenGL Performer application that does not try to place multiple processes on the same processor or a non-realtime application does not have to set this flag.

There are some restrictions on which functions can be called from an OpenGL Performer process while multiple processes are running. Some specialized processes (such as the process handling the draw stage) can call only a few specific OpenGL Performer functions and cannot call any other kinds of functions. This section lists general and specific rules concerning function invocation in the various OpenGL Performer and user processes.

In this section, the phrase “the draw process” refers to whichever process is handling the draw stage, regardless of whether that process is also handling other stages. Similarly, “the cull process” and “the application process” refer to the processes handling the cull and application stages, respectively.

This is a general list of the kinds of routines you can call from each process:

More specific elaborations:

In OpenGL Performer, as is often true of multiprocessing systems, memory management is the most difficult aspect of multiprocessing. Most data management problems in an OpenGL Performer application can be partitioned into three categories:

Fortunately, OpenGL Performer transparently solves all of the problems just described for most OpenGL Performer data structures and also provides powerful tools and mechanisms that the application can use to manage its own memory.

The pfInit() function creates a shared memory arena that is shared by all processes spawned by OpenGL Performer and all user processes that are spawned from any OpenGL Performer process. A handle to this arena is returned by pfGetSharedArena() and should be used as the arena argument to routines that create data that must be visible to all processes. Routines that accept an arena argument are the pfNew*() routines found in the libpr library and the OpenGL Performer memory allocator, pfMalloc(). In practice, it is usually safest to create libpr objects like pfGeoSets and pfMaterials in shared memory. libpf objects like pfNodes are always created in shared memory.

Allocating shared memory does not by itself solve the memory visibility problem discussed above. You must also make sure that the pointer that references the memory is visible to all processes. OpenGL Performer objects, once incorporated into the database through routines like pfAddGSet(), pfAddChild(), and pfChanScene(), automatically ensure that the object pointers are visible to all OpenGL Performer processes.

However, pointers to application data must be explicitly shared. A common way of doing this is to allocate the shared memory after pfInit() but before pfConfig() and to reference the memory with a global pointer. Since the pointer is set before pfConfig() forks any processes, these processes will all share the pointer's value and can thereby access the same shared memory region. However, if this pointer value changes in a process, its value will not change in any other process, since forked processes do not share the same address space.

Even with data visible to all processes, data exclusion is still a problem. The usual solution is to use hardware spin locks so that a process can lock the data segment while reading or writing data. If all processes must acquire the lock before accessing the data, then a process is guaranteed that no other processes will be accessing the data at the same time. All processes must adhere to this locking protocol, however, or exclusion is not guaranteed.

In addition to a shared memory arena, pfInit() creates a semaphore arena whose handle is returned by pfGetSemaArena(). Locks can be allocated from this semaphore arena by usnewlock() and can be set and unset by ussetlock() and usunsetlock(), respectively.

The pfDataPools—named shared memory arenas with named allocation blocks—provide a complete solution to the memory visibility and memory exclusion problems, thereby obviating the need to set global pointers between pfInit() and pfConfig(). For more information about pfDataPools, see the pfDataPools man page.

The techniques discussed thus far do not solve the memory synchronization problem. OpenGL Performer's libpf library provides a solution in the form of passthrough data. When using pipelined multiprocessing, data must be passed through the processing pipeline so that data modifications reach the appropriate pipeline stage at the appropriate time.

Passthrough data is implemented by allocating a data buffer for each stage in the processing pipeline. Then, at well-defined points in time, the passthrough data is copied from its buffer into the next buffer along the pipeline. This copying guarantees memory exclusion, but you should minimize the amount of passthrough data to reduce the time spent copying.

Allocate a passthrough data buffer for the rendering pipeline using pfAllocChanData(); for data to be passed down the intersection pipeline, call pfAllocIsectData(). Data returned from pfAllocChanData() is passed to the channel cull and draw callbacks that are set by pfChanTravFunc(). Data returned from pfAllocIsectData() is passed to the intersection callback specified by pfIsectFunc().

Passthrough data is not automatically passed through the processing pipeline. You must first call pfPassChanData() or pfPassIsectData() to indicate that the data should be copied downstream. This requirement allows you to copy only when necessary—if your data has not changed in a given frame, simply do not call a pfPass*() routine, and you will avoid the copy overhead. When you do call a pfPass*() routine, the data is not immediately copied but is delayed until the next call to pfFrame(). The data is then copied into internal OpenGL Performer memory and you are free to modify your passthrough data segment for the next frame.

Modifications to all libpf objects—such as pfNodes and pfChannels—are automatically passed through the processing pipeline, so frame-accurate behavior is guaranteed for these objects. However, in order to save substantial amounts of memory, libpr objects such as pfGeoSets and pfGeoStates do not have frame-accurate behavior; modifications to such objects are immediately visible to all processes. If you want frame-accurate modifications to libpr objects you must use the passthrough data mechanism, use a frame-accurate pfSwitch to select among multiple copies of the objects you want to change, or use the pfCycleBuffer memory type.

You can overcome the loose-culling problem by allocating extra processes for cleaning up the pfGeoSet lists that the CULL processes produce. These extra processes are called CULL sidekicks. By default, a CULL sidekick process checks all the primitives in all pfGeoSets on the CULL output. It replaces original pfGeoSets with temporary pfGeoSets and populates the temporary pfGeoSets with the visible parts of the original pfGeoSets. By default, CULL sidekick processes test each primitive twice for the following:

CULL sidekick processes run side-by-side with their CULL process. They do not interact with the CULL process during its frame, but they merely patch the visible pfGeoSet list as the CULL process populates it. This means that configuring CULL sidekick processes does not add any latency to the application.

Figure 5-8 shows how CULL_SIDEKICK optimizes visible pfGeoSet lists while CULL is writing them. The figure shows three CULL_SIDEKICK processes working on the visible pfGeoSet list that a CULL process produces. Visible pfGeoSet#1 is replaced by Temporary pfGeoSet#1. Visible pfGeoSet#2 contains no visible primitives and is skipped entirely.

Figure 5-8. CULL_SIDEKICK Processing

Each CULL process can have multiple CULL_SIDEKICK processes. You can use the pfMultithread() call to specify the number of CULL_SIDEKICK processes for each CULL process. The collection of CULL_SIDEKICK processes configured for each CULL process traverses in a round-robin manner the pfGeoSet list that the CULL process produces. The more CULL_SIDEKICK processes (each assigned to a separate CPU), the faster they process the pfGeoSet list that the CULL process produces.

Using the function pfMultithreadParami() and the parameter PFSK_OPTIMIZATION, an application can specify a bit-wise OR of the constants PFSK_BACKFACE_CULL and PFSK_FRUSTUM_CULL. Specifying the PFSK_BACKFACE_CULL flag instructs CULL_SIDEKICK to run a backface test on each primitive and to remove backfacing primitives. This mode is aware of the pfGeoState setting for each pfGeoSet and correctly ignores pfGeoSets that do not require this test. Specifying the PFSK_FRUSTUM_CULL flag instructs CULL_SIDEKICK to run a frustum test on each primitive and to remove primitives outside the viewing frustum. Both of these tests break triangle strips, line strips, and triangle fans if portions of these are invisible.

---

Note: It is safe to change the CULL_SIDEKICK optimization mask on the fly.

---

Since traversing the visible pfGeoSet list that CULL produces may take longer than a single frame, you can specify a policy for the behavior of CULL_SIDEKICK processes.

Using the function pfMultithreadParami() and the parameter PFSK_POLICY, you can specify one of three options:

Use the function pfMultithreadParami() with parameters PFSK_USER_FUNC and PFSK_USER_FUNC_DATA to register a callback function for the CULL_SIDEKICK pfGeoSet optimization. When specified, a CULL_SIDEKICK calls the callback function instead of running the default optimization. The CULL_SIDEKICK provides the callback function with a target pfGeoSet. The callback function can clone the target pfGeoSet, modify the cloned pfGeoSet, and return it as a replacement for the target pfGeoSet.

The callback function should return a pfGeoSet pointer. It can return one of the following values:

The callback function receives as a parameter a pointer to a pfDispListOptimizer class. The callback function can use this pointer in order to do the following:

The following is a sample callback function. This function clones the incoming pfGeoSet, jitters all its coordinates by a random amount, and replaces all its colors by random colors:

pfGeoSet *
userFunction(pfGeoSet *gset, pfDispListOptimizer *op, void *userData)
{
	pfGeoSet    *new_gset;
	ushort      *ilist;
	int         *len;
	float       *c;
	float       *v;
	int         numVerts, numPrims, numColors;
	int         i;

	/* Modify geosets with line-strip/tri-strip primitives only. */
	/* When not modifying a pfGeoSet, return its original pointer. */
	if ((pfGetGSetPrimType(gset) != PFGS_LINESTRIPS) &&
		(pfGetGSetPrimType(gset) != PFGS_TRISTRIPS))
		return (gset);

	/* Clone geoset. We can modify the cloned geoset because it */
	/* is temporary for this CULL process for this frame. */
	new_gset = pfDLOptimizerCloneGSet(op, gset, 
					PFSK_COORD3 |PFSK_NORMAL3 |
					PFSK_TEXCOORD2 |PFSK_ATTR_LENGTHS);

	/* Get pointers to cloned geoset attributes */
	pfGetGSetAttrLists(new_gset, PFGS_COLOR4, &c, &ilist);
	if (ilist) return gset; /* ignore indexed gsets */
	pfGetGSetAttrLists(new_gset, PFGS_COORD3, &v, &ilist);
	if (ilist) return gset; /* ignore indexed gsets */
	len = pfGetGSetPrimLengths(new_gset);
	numPrims = pfGetGSetNumPrims(new_gset);

	/* Count how many vertex entries in the COORD3 attribute. */
	numVerts = 0;
	for (i = 0 ; i < numPrims ; i ++)
		numVerts += len[i];

	/* Count how many color entries in the COLOR4 attribute. */
	switch (pfGetGSetAttrBind(gset, PFGS_COLOR4))
	{
		case PFGS_PER_VERTEX:
			numColors = numVerts;
			break;
		case PFGS_PER_PRIM:
			numColors = numPrims;
			break;
		case PFGS_OVERALL:
			numColors = 1;
			break;
		case PFGS_OFF:
			numColors = 0;
			break;
	}
	/* Pick a random color for each color entry in the cloned */
	/* color attribute array. 	*/
	for (i = 0 ; i < numColors ; i ++)
	{
		*(c++) = getRand(); *(c++) = getRand(); *(c++) = getRand();
		*(c++) = 1.0;
	}
	/* Pick a random perturbation for each coordinate */
	for (i = 0 ; i < numVerts ; i ++)
	{
		*(v++) += vertex_jitter_amount * getRand();
		*(v++) += vertex_jitter_amount * getRand();
		*(v++) += vertex_jitter_amount * getRand();
	}
	/* Send new geoset for default frustum/backface culling. */
	return pfDLOptimizerOptimize(op, new_gset);
}

When cloning a pfGeoSet from within a CULL_SIDEKICK callback function, you may wish to modify the pointers to the attribute arrays of the cloned pfGeoSet. Cloned pfGeoSets are temporary and do not require reference counting. Use the following quick methods on the pfGeoSet in order to manipulate its attributes:

Use the function pfGSetOptimize() to mark any single pfGeoSet for optimization by the CULL_SIDEKICK process. By default, all pfGeoSets under a pfGeode node undergo optimization. All pfGeoSetCBs are not optimized by default but can be optimized using this function. No pfGeoSet under a pfBillboard node is ever optimized (regardless of the optimization flag setting).