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:

A compositor is a hardware device that takes a number of video inputs and combines them to produce a single video output. The video inputs can be divided spatially or blended together to form one output. OpenGL Performer uses the pfCompositor class to support compositors. The pfCompositor class transparently distributes rendering across multiple hardware pipes and combines their outputs by either feeding them to a hardware compositor device or through software composition.

Several different spatial composition modes are supported, as well as an antialias mode in which channel frustums on composited pipes are slightly jittered and the outputs blended together by the hardware compositor.

The pfCompositor class also supports dynamic load balancing. When enabled, the spatial subdivision of the compositor inputs will be updated on each frame based on the load of each contributing pfPipe. Load balancing is disabled by default but can be enabled through setMode().

During initialization, the pfCompositor class will perform a system topology query to determine the availability of hardware compositors. The results of this query can be examined by the application through the static methods listed in Table 14-2.

A pfCompositor is created through new pfCompositor(netId), where netId is the network ID for the hardware compositor device that will be managed by the new pfCompositor. If netId is PFCOMP_SOFTWARE, no hardware compositor device will be involved, and composition will be carried out through software readbacks.

This chapter refers to pfCompositors utilizing software composition as software compositors while pfCompositors associated with a hardware compositor device will be referred to as hardware compositors.

You can use the methods described in Table 14-3 to configure pfCompositors that have been created.

The methods described in Table 14-4 can be used to query compositors.

In addition to the methods shown in Table 14-4, the static methods shown in Table 14-5 are also available.

A pfCompositor requires a pfLoadBalance object for carrying out load balancing computations. The pfLoadBalance class determines the resulting workload for each of the compositor's children. The behavior can be customized by subclassing pfLoadBalance and overriding the appropriate methods. A pfCompositor can use a customized pfLoadBalance object specified through the setLoadBalancer() method. If a load balancer is not specified, one will be automatically created and used. The method getLoadBalancer() returns a pointer to the pfLoadBalancer object used by the compositor.

The two methods in Table 14-6 can be used to control the transition between load balancing states.

For more information, see the pfLoadBalance man page.

The method setMode() accepts the following tokens as its first argument:

All composition modes are valid for any number of active children.

Figure 14-6 illustrates how one to four inputs are laid out for PFCOMP_COMPMODE_HORIZ_STRIPES mode.

Figure 14-6. Horizontal Stripes (pfCompositor Mode)

Figure 14-7 illustrates how one to four inputs are laid out for PFCOMP_COMPMODE_VERT_STRIPES mode.

Figure 14-7. Vertical Stripes (pfCompositor Mode)

Figure 14-8 illustrates how one to four inputs are laid out for PFCOMP_COMPMODE_LEFT_TILES mode.

Figure 14-8. Left Tiles (pfCompositor Mode)

Figure 14-9 illustrates how one to four inputs are laid out for PFCOMP_COMPMODE_RIGHT_TILES mode.

Figure 14-9. Right Tiles (pfCompositor Mode)

Figure 14-10 illustrates how one to four inputs are laid out for PFCOMP_COMPMODE_BOTT_TILES mode.

Figure 14-10. Bottom Tiles (pfCompositor Mode)

Figure 14-11 illustrates how one to four inputs are laid out for PFCOMP_COMPMODE_TOP_TILES mode.

Figure 14-11. Top Tiles (pfCompositor Mode)

The method getMode() can be called to query the compositor mode. You can use the following tokens:

You can use the methods described in Table 14-7 to manage screen space, channel clipping, and antialiasing.

---

Note: All viewports are specified in normalized screen coordinates with 0.0,0.0 as the bottom-left corner of the screen and 1.0,1.0 as the top-right corner.

---

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)