A pfH yperpipe is a combination of pfPipes or pfMultipipes; there is one pfPipe for each graphics pipe in a DPLEX ring or chain. A DPLEX ring or chain is a collection of interconnected graphic boards.

A key concept with hyperpipes is that of temporal decomposition. Think of a rendered sequence as a 3D data set with time being the third axis. With temporal decomposition, the dataset is subdivided along the time axis and distributed across, in this case, each of the graphic pipes in the hyperpipe group.

Temporal decomposition is different from spatial decomposition, in which the dataset is subdivided along the X axis, Y axis, or both X and Y axes.

It is the responsibility of the application to establish the hyperpipe group configuration for OpenGL Performer. There are two steps in the configuration process:

Establishing the Number of Graphic Pipes

Use the argument in the pfHyperpipe() function to establish the number of graphic pipes in the hyperpipe group, for example:

pfHyperpipe(2); pfConfig();

In this example, two pfPipes combine to create the pfHyperpipe, as shown in Figure 14-1.

Figure 14-1. pfPipes Creating pfHyperpipes

Like the pfMultipipe() function, pfHyperpipe() must be invoked prior to configuring the pfPipes using pfConfig() and after the call to pfInit().

The number of pipes is used by pfConfig() to associate the configured pfPipes. The pfHyperpipe() function can be invoked multiple times to construct multiple hyperpipe groups, as shown in Figure 14-2.

Figure 14-2. Multiple H yperpipes

Additionally, the pfHyperpipe() function can be combined with the pfMultipipe() call to configure pfPipes that are not associated with a hyperpipe group. The num argument to the pfMultipipe() function defines the total number of pfPipes to configure (including those in hyperpipe groups).

Example 14-1, diagrammed in Figure 14-2, shows the configuration of a system with three hyperpipe groups. The first hyperpipe group consists of three graphic pipes. The remaining two hyperpipe groups have two graphic pipes each. This example also configures one non-hyperpipe group graphic pipe.

Example 14-1. Configuring a System with Three Hyperpipe Groups

pfInit(); pfMultipipe(8); /* need eight pfPipes 3-2-2-1 */ pfHyperpipe(3); /* pfPipes 0, 1, 2 are the first group */ pfHyperpipe(2); /* pfPipes 3, 4 are the second group */ pfHyperpipe(2); /* pfPipes 5, 6 are the third group */ pfConfig(); /* construct the pfPipes */

If the target configuration includes only hyperpipe groups, it is not necessary to invoke pfMultipipe(). OpenGL Performer correctly determines the number of pfPipes from the pfHyperpipe() calls.

Using the Default Hyperpipe Mapping to Graphic Pipes

The pfPipes constructed by pfConfig() are ordered into a linear array and are selected with the pfGetPipe() function. The pfPipes that are part of a hyperpipe group always appear in this array before any non-hyperpipe group pfPipes.

The pfHyperpipe() function groups pfPipes together starting, by default, with pfPipe number 0. In the following example, there are four pfPipes; the first two are combined into a hyperpipe group:

pfMultipipe(4); pfHyperpipe(2); pfConfig();

OpenGL Performer maps each pfPipe to a graphic pipe, which is associated with a specific X display, as shown in Figure 14-3:

Figure 14-3. Default Hyperpipe Mapping to Graphic Pipes

/* assign the single pfPipe to screen 0 */
pfPipeScreen(pfGetPipe(7), 0);

/* assign the pfPipes of hyperpipe group 0 to screens 1,2,3 */
for (i=0; i < 3; i++)
pfPipeScreen(pfGetPipe(i), i+1);
	
/* assign the pfPipes of hyperpipe group 1 to screens 4,5 */
for (i=3; i<5; i++)
    pfPipeScreen(pfGetPipe(i), i+1);

/* assign the pfPipes of hyperpipe group 2 to screens 6,7 */
for (i=5; i<7; i++)
    pfPipeScreen(pfGetPipe(i), i+1);

int hasHyperpipe;
	GLXHyperpipeNetworkSGIX* hyperNet;
	int numHyperNet;
	int i;
	Display* dsp;
	int numNet;
	int pipeIdx;
	pfChannel* masterChan;

	/* initialize Performer */
	pfInit();

	/* does this configuration support hyperpipe */
	pfQueryFeature(PFQFTR_HYPERPIPE, &hasHyperpipe);
	if (!hasHyperpipe) {
	    pfNotify(PFNFY_FATAL, PFNFY_RESOURCE, "no hyperpipe support");
	    exit(1);
	}

	/* query the network */
	dsp = pfGetCurWSConnection();
	hyperNet = glXQueryHyperpipeNetworkSGIX(dsp, &numHyperNet);
	if (numHyperNet == 0) {
	    pfNotify(PFNFY_FATAL, PFNFY_RESOURCE, "no hyperpipes");
	    exit(1);
	}

	/*
	 * determine the number of distinct hyperpipe networks. network
	 * ids are monotonically increasing from zero. a value < 0
	 * is used to indicate pipes that are not members of any hyperpipe.
	 */
	for (i=0, numNet=-1; i<numHyperNet; i++)
	    if (numNet < hyperNet[i].networkId)
		numNet = hyperNet[i].networkId;
	numNet += 1;

	/*
	 * configure all of the hyperpipes in the net
	 *
	 * NOTE -
	 * while it is possible to be selective about which hyperpipe(s)
	 * to configure, that is left as an exercise.
	 */
	for (i=0; i<numNet; i++) {
	    int count = 0;
	    int j;
	    for (j=0; j<numHyperNet; j++)
    		if (hyperNet[i].networkId == i) count++;
	    pfHyperpipe(count);
	}

	pfConfig();

	/* associate pfPipes with screens */
	for (i=0, pipeIdx=0; i<numNet; i++) {
	    int j;
	    for (j=0; j<numHyperNet; j++)
    		if (hyperNet[i].networkId == i)
		    pfPipeWSConnectionName(pfGetPipe(pipeIdx++),
			    hyperNet[i].pipeName);
	}

	/* construct the pfPipeWindows for each hyperpipe */
	masterChan = NULL;
	for (i=0, pipeIdx=0; i<numNet; i++) {
	    pfPipe* pipe;
	    pfPipeWindow* pwin;
	    pfChannel* chan;
	    PFVEC3 xyz, hpr;

	    pipe = pfGetPipe(pipeIdx);
	    pwin = pfNewPWin(pipe);
	    pfPWinName(pwin, "Hyperpipe Window");

	    /*
	     * void
	     * openPipeWindow(pfPipeWindow* pwin)
	     * {
	     *     pfPWinOpen(pwin);
	     * }
	     */
	    pfPWinConfigFunc(pwin, openPipeWindow);
	    pfPWinFullScreen(pwin);
	    pfPWinMode(pwin, PFWIN_NOBORDER, 1);
	    pfPWinConfig(pwin);

	    chan = pfNewChan(pipe);
	    pfPWinAddChan(pwin, chan);

	    /*
	     * layout channels left to right in hyperpipe order. this
	     * ordering is arbitrary and should be redefined for the
	     * specific application.
	     */
	    pfChanShare(chan,
		    pfGetChanShare() | PFCHAN_VIEWPORT |
		    PFCHAN_SWAPBUFFERS | PFCHAN_SWAPBUFFERS_HW);
	    pfMakeSimpleChan(chan, 45);
	    pfChanAutoAspect(chan, PFFRUST_CALC_VERT);

	    xyz[0] = xyz[1] = xyz[2] = 0;
	    hpr[0] = (((numNet-1)*.5f)-i)*45.f;
	    hpr[1] = hpr[2] = 0;
	    pfChanViewOffsets(chan, xyz, hpr);
	    pfChanNearFar(.000001, 100000);

	    /*
	     * void
	     * drawFunc(pfChannel* chan, void* notUsed)
	     * {
	     *     pfClearChan(chan);
	     *     pfDraw();
	     * }
	     */
	    pfChanTravFunc(PFTRAV_DRAW, drawFunc);
	    if (i == 0)
		       masterChan = chan;
	    else
       		pfAttachChan(masterChan, chan);

	    /* bump to the first pipe of the next hyperpipe */
	    pipeIdx += pfGetHyperpipe(pipe);
	}

	/*
	 * the next step is to construct the scene, attach it to
	 * masterChan and start the main loop. this bit of code
	 * is not included here since it follows other demonstration
	 * applications included elsewhere in the Programmer's Guide.
	 */

The pfPipes grouped into a pfHyperpipe are indexed; the first pfPipe is pfPipe(0) and it is referred to as the master pfPipe. Most actions taken on the hyperpipe group are effected through this pfPipe; for example, all objects, such as pfPipeWindows and pfC hannels, are attached to the master pfPipe. OpenGL Performer automatically clones all objects, except pfChannels, across all of the pfPipes in the pfHyperpipe, as shown in Figure 14-4.

Figure 14-4. Attaching Objects to the Master pfPipe

When constructing pfPipeWindows or pfChannels, the pfPipe argument should be the master pfPipe. OpenGL Performer ensures that the constructed objects are cloned (pfPipeWindows) or attached (pfChannels) as needed to the other pfPipes in the hyperpipe group.

 With the exception of certain attributes, detailed in Table 14-1, OpenGL Performer propagates attribute updates to the cloned pfPipeWindows when they occur. The following is a list of pfPipeWindow functions for which the attributes do not propagate.

When using any of the preceding interfaces within an application, set the appropriate attribute in the cloned pfPipeWindow.

static int attr[] = { 
	    GLX_RGBA,
	    GLX_DOUBLEBUFFER,
	    GLX_LEVEL, 0,
	    GLX_RED_SIZE, 8,
	    GLX_GREEN_SIZE, 8,
	    GLX_BLUE_SIZE, 8,
	    GLX_ALPHA_SIZE, 8,
	    GLX_DEPTH_SIZE, 16,
	    GLX_STENCIL_SIZE, 0,
	    GLX_ACCUM_RED_SIZE, 0,
	    GLX_SAMPLE_BUFFERS_SGIS, 1,
	    GLX_SAMPLES_SGIS, 4,
	    None
	};

	int numHyper = pfGetHyperpipe(pfGetPipe(0));
	for (i=0; i<numHyper; i++) {
	    /* get the first pfPipeWindow on pfPipe */
	    pfPipeWindow* pwin = pfGetPipePWin(pfGetPipe(i), 0);
	    pfPipeFBConfigAttrs(pwin, attr);
}

/* search the master pfPipe pipe for the pfPipeWindow in pwin */
	int pwinIdx;
	int numPWins = pfGetPipeNumPWins(pipe);
	for (i=0; i<numPWins; i++)
	    if (pfGetPipePWin(pipe) == pwin) break;
	if (i == numPWins)
	    pfNotify(PFNFY_FATAL, PFNFY_PRINT, "oops!");
	pwinIdx = i;

Programming with hyperpipes, as described in the preceding sections, generally involves the following steps:

There are two additional requirements for DPLEX:

Each pfPipe software rendering pipeline runs at a fraction of the target frame rate as defined by pfFrameRate(). The fraction is 1/(number of pipes in hyperpipe group). For example, if there are two pfPipes in the pfHyperpipe, each pfPipe runs at one half of the pfFrameRate(). Although the CULL and DRAW stages run at a slower rate, the APP stage must run at the target frame rate.

The compositor receives two to four input signals and outputs a single signal either in analog or digital format. Hence, it can handle spatial composition of four inputs which enables multiple pipes to contribute to a single output. Four different composition schemes are available:

Figure 14-5 illustrates the various hardware composition schemes.

Figure 14-5. Hardware Composition Schemes

The following items are noteworthy regarding the compositor's capabilities:

The pfCompositor class provides methods for controlling a single compositor or a heirarchy of compositors. The class provides methods for setting the subdivision of the inputs for the compositor to use. The subdivision is set by specifying the viewports and frusta for each input.

The pfCompositor class also allows for automatically setting the subdivision based on the load of each pfPipe providing an input. The subdivision pfCompositor performs can be controlled by setting the subdivision mode. By default, automatic load balancing is enabled and the subdivision mode is a 2x2 arrangement. Figure 14-6 illustrates some decomposition modes available for pfCompositor.

Figure 14-6. Decomposition Modes for pfCompositor

A pfCompositor requires a pfLoadBalance class for doing the load balancing of each of its children. The pfLoadBalance class determines the resulting workload for each pipe. The behavior can be customized by subclassing pfLoadBalance and overriding the appropriate methods. A pfCompositor can use a customized pfLoadBalance class specified using the pfCompositorLoadBalancer() function. If a load balancer is not specified, one will automatically be created and used. See the pfLoadBalance man page for more information on pfLoadBalance.

Antialiasing is supported as another type of subdivision mode and is enabled with the function pfCompositorMode().

Table 14-2 describes the functions for managing compositors.

The pfLoadBalance class encapsulates an algorithm for distributing any incoming workload among multiple servants. The class maintains history information about the following:

Based on this information, pfLoadBalance computes a new workload distribution to minimize the time needed for completing the input workload.

The default implementation keeps track of a single frame of history. Subclasses of pfLoadBalance could track history information through multiple frames. Using multiple frames, the subclasses can compute the rate of change in the work allocation to workload ratio.

The default implementation tries to smooth the transition as workload allocation changes for each servant. Subclasses of pfLoadBalance could also change the smoothing factors to match the rate of change in workload between consecutive frames.

The following psuedo code illustrates a typical use of pfLoadBalance from pfCompositor:

// Set the number of servants to balance this frame.

pfLoadBalanceNumActive()

foreach child

// Tell the load balancer what the current load is on the child.

   pfLoadBalanceLoad()

end

balance()

foreach child

// Get the percentage of the work this child should perform.

    pfGetLoadBalanceWork()

end

Table 14-3 describes the functions you can use to manage load balancing.

OpenGL Performer implements GPU programming through the general class pfGProgram. This class allows you to set GPU programs, vertex programs and fragment programs.

The function pfNewGProgram() creates and returns a handle to a pfGProgram. The parameter arena specifies a malloc() arena out of which the pfGProgram is allocated or the value NULL specifies allocation off the process heap. pfGPrograms can be deleted with pfDelete().

The call new(arena) allocates a pfGProgram from the specified memory arena or from the heap if arena is NULL. The new() call allocates a pfGProgram from the default memory arena (see function pfGetSharedArena() in the pfSharedMem(3pf) man page). Like other pfObjects, pfGPrograms cannot be automatically created statically on the stack or in arrays. pfGPrograms should be deleted with pfDelete() rather than the delete operator.

The function pfGetGProgramClassType() returns the pfType* for the class pfGProgram. The pfType* returned by pfGetGProgramClassType() is the same as the pfType* returned by invoking pfGetType(), the virtual function getType() on any instance of class pfGProgram. 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(), the member function isOfType(), to test if an object is of a type derived from an OpenGL Performer type rather than to test for strict equality of the types.

A pfGProgram is a sequence of assembly-like instructions. You can specify the instructions in two ways:

If the program is specified in a string, you use the function pfGProgramProgram() or pfGProgramProgramLen(). The first parameter of each is the string defining the program. In the second function, you can specify the length when you want to load only part of the string.

If the program is loaded from a text file, you use the function pfGProgramLoadProgram().

Using the function pfGProgramApplypfGProgram(), you can apply the pfGProgram but only in the draw process. Once the pfGProgram has been applied, you can query its state using the following functions:

You should not use a pfGProgram directly but one of its subclasses. There are two classes of specific GPU programs subclassed from pfGProgram: pfVertexProgram and pfFragmentProgram. A pfVertexProgram or a pfFragmentProgram is set in a pfGeoState and is enabled in a pfGeoState. The user parameters for the vertex and fragment programs can be defined using the class pfGProgramParams, which is described in the following section.

For sample code, see the following file:

/usr/share/Performer/src/pguide/libpf/C++/gprogram.C
(IRIX and Linux)
%PFROOT\Src\pguide\libpf\C++\gprogram.cxx
(Microsoft Windows)

The pfGProgramParms is a class that is used to store parameters of GPU programs, specifically of pfVertexPrograms and pfFragmentPrograms. The function pfNewGProgramParms() creates and returns a handle to a pfGProgramParms. The parameter arena specifies a malloc() arena out of which the pfGProgram is allocated or NULL for allocation off the process heap. You can delete pfGPrograms with pfDelete().

A pfGProgramParms is a set of indexed quadruples of floating point values that are used as parameters for vertex and fragment programs. You can specify the values using the function pfGPParamsParameters() which has the following syntax:

pfGPParamsParameters(pfGProgramParms* gpparams, int index, int type, int count, void* ptr);

The parameter index specifies the first index of the specified parameters (the index by which the parameters are accessed in the GPU program) and the the parameter count specifies how many indices will be set.

The parameter type may be one of the following:

The pointer ptr points to the parameter data.

Using the following functions, you can query the existing parameters in a pfGProgramParms:

You can apply the pfGProgramParms using pfGProgramParamsApply() but only in the draw process. If you modify the pfGProgramParms after they have been applied, you must call pfGProgramParamsUpdate() for the change to take effect.

A pfGProgramParms is set in a pfGeoState. Each pfGeoState can have one pfGProgramParms of each of the four types, two for the pfVertexProgram associated with the pfGeoState and two for the pfFragmentProgram.

The pfVertexProgram and pfFragmentProgram classes are derived from the class pfGProgram. These subclasses do not add any new methods. A vertex program or a fragment program is used by the GPU to modify various parameters of each vertex or fragment (pixel), respectively. The GPU allows you to specify a sequence of floating-point 4-component operations that are executed for each vertex or fragment. These operations transform an input set of per-vertex or per-fragment parameters to another set of per-vertex or per-fragment parameters.

A vertex program replaces the standard OpenGL set of lighting and texture coordinate generation modes. Consequently, the vertex program must take care of the basic transformation of vertex coordinates to the screen coordinates, the generation of texture coordinates, and the application of the lighting equation. This programming model allows you to modify the position of each vertex, producing, for example, a displacement mapping.

Similar to a vertex program, a fragment program replaces the standard OpenGL set of texture and fog application modes. The fragment program has to access the textures and to modulate the resulting color according to the fog equation, if necessary. This programming model allows you to modify the resulting color and depth of each pixel, making it possible, for example, to apply a complex per-pixel shading.

You can find the instruction sets for vertex and fragment programs in the OpenGL extension registry at http://oss.sgi.com/projects/ogl-sample/registry/ under the GL_ARB_vertex_program.

As subclasses of pfGProgram, pfVertexPrograms and pfFragmentPrograms can use the management methods of a pfGProgram to set, load, and apply programs. Section “The pfGProgram Class” describe these methods.

You set and enable pfVertexPrograms and pfFragmentPrograms in a pfGeoState. As described in section “The pfGProgramParms Class”, the user parameters for GPU programs can be defined using the pfGProgramParms class.

For sample code, see the following file:

/usr/share/Performer/src/pguide/libpf/C++/gprogram.C
(IRIX and Linux)
%PFROOT\Src\pguide\libpf\C++\gprogram.cxx
(Microsoft Windows)