hyperpipe(3)

NAME
     GLX_SGIX_hyperpipe - hyperpipe extension

DESCRIPTION
     Even though graphics hardware is constantly improving in speed, there
     will always be applications that require more performance than is
     available from a single pipeline. In order to overcome these limits, it
     is possible to parallelize the rendering task across multiple pipes; the
     image outputs of these pipes must then be assembled into a single display
     output. This group of pipes is termed a hyperpipe; the pipes involved
     must be physically cabled together in some way to form a hyperpipe
     network. Typically a hyperpipe network uses one of the pipes to assemble
     the rendered images and drive the display.

     In a hyperpipe network, the rendering task may be divided by rendering
     each successive frame on a different hardware pipe (temporal division);
     by dividing the frame into rectangular subregions and rendering each on a
     different pipe (spatial division); or by a combination of these two
     techniques. Specific hardware implementations may impose limits on how
     rendering may be subdivided; but in general it is possible to use a
     subset of the pipes connected to a hyperpipe network if desired.

     This extension provides a means for configuring and managing a group of
     rendering pipes which work together to produce a single display.
     Typically, a hyperpipe application will be multi threaded, with one
     thread per pipe; each thread needs to create its own rendering context.
     The hyperpipe extension allows these rendering threads to communicate
     with the hardware.

     The API calls allow an application to:

     o  Determine the physical configuration of a hyperpipe network.

     o  Configure the hyperpipe. The hyperpipe configuration used by the
        application may be a subset of the physical hyperpipe network.
        The rendering task may be divided in time slices (temporally divided),
        in rectangular regions of a single frame (spatially divided), or both.
        The hyperpipe configuration is subject to hardware constraints.

        For example, on a hyperpipe network consisting of five pipes, it
        would be possible to configure a rendering task in two time slices,
        with each slice being rendered by two pipes; thus using four total
        pipes. (The fifth pipe would not be used in the hyperpipe, and
        could be used for normal non-hyperpipe rendering and display).

     o  Maintain state to manage the glXSwapBuffers  call correctly. In
        spatial subdivision, swap cannot occur until all pipes rendering
        the next frame have completed; and in temporal subdivision, swap
        cannot occur until the appropriate time. Swap management is
        handled by the displaying pipe.

     o  Redirect resize parameters correctly; typically resize is handled
        by the displaying pipe, and must be managed synchronously with
        swap.

     o  Balance load among the pipes in the spatial subdivision case.

     o  Clean up operations when a hyperpipe application terminates
        (either normally or due to error).

     This extension adds to the set of conditions that must be met before a
     buffer swap can take place.

FUNCTIONS
     The main functions are:

     glXQueryHyperpipeNetworkSGIX - query the physical hyperpipe network.

     glXHyperpipeConfigSGIX - configure the hyperpipe network.

     glXQueryHyperpipeConfigSGIX - query a particular hyperpipe configuration.

     glXDestroyHyperpipeConfigSGIX - destroy a hyperpipe configuration.

     glXBindHyperpipeSGIX - bind a process and rendering context to a
     hyperpipe configuration.

NOTES
     In addition to its usual functionality, the glXSwapBuffers call on a
     rendering context bound to a hyperpipe causes the hyperpipe display
     output to switch to the next pipe of the network.

     Hyperpipes cannot function on single buffered visuals; double buffered
     visuals are required on all bound graphics contexts.

     The hyperpipe id associated with a context can be determined by calling
     glXQueryContextInfoEXT with an attribute of GLX_HYPERPIPE_ID_SGIX.

SAMPLE CODE
     Typically, a hyperpipe application will have a master process which:

     o Queries the hyperpipe network;

     o Chooses which of the pipes on the hyperpipe network to use;

     o Sets up a hyperpipe configuration using the above pipes;

     o Forks off one (or more) rendering processes per pipe.

     Each of the created child processes will:

     o Create its own window and a direct rendering graphics context;

     o Binds the rendering context to the hyperpipe id supplied by
       the master process.

     Master Process

          GLXHyperpipeNetworkSGIX * nw;
          GLXHyperpipeConfigSGIX cfg[32];
          char * extString;

          /* Open the default display */
          dpy = XOpenDisplay( 0 );

          scr = DefaultScreen( dpy );

          /* Query the extension string to verify that the
          ** hyperpipe extension is present
          */

          extString = (char *)glXQueryExtensionsString(dpy,scr);

          if (!strstr( extString, "GLX_SGIX_hyperpipe")) {
               /* Abort */
          }

          /* Query the hyperpipe network */

          nw  = glXQueryHyperpipeNetworkSGIX(dpy, &npipes);
          if ( (nw== NULL) || (npipes == 0 ) ) {
               /* No hyperpipe network, Abort */
          }

          /* Choose some pipes from the above list in nw and fill in the
          ** configuration structure
          ** The sample code below sets up a 3 pipe hyperpipe
          */

          nid = nw[0].networkId;
          npipes = 2;

          for (i=0; i<npipes; i++) {

               strcpy (cfg[i].pipeName, nw[i].pipeName);
               cfg[i].participationType = GLX_HYPERPIPE_RENDER_PIPE_SGIX;
               cfg[i].timeSlice = i;
               cfg[i].channel = 0;
          }

          /* Choose the first pipe to be the display pipe also */

          cfg[0].participationType |=  GLX_HYPERPIPE_DISPLAY_PIPE_SGIX;
          if (glXHyperpipeConfigSGIX( dpy,
               nw[0].networkId,
               npipes,
               cfg,
               &hpId)
               == GLX_BAD_HYPERPIPE_CONFIG_SGIX) {

               /*Something wrong with the hyperpipe configuration;Abort */
          }

          /* Don't need the hyperpipe network information any more */

          XFree (nw);

          /*Now fork npipes number of process */

          /* hang around untill all child processes finish */
          glXDestroyHyperpipeConfigSGIX(dpy, hpId);


     Each child process then calls :

          /* Open Display and screen */

          /* sanity checking to ensure that the hyperpipe
          ** is present on the required pipes
          */

          extString = (char *)glXQueryExtensionsString(dpy,scr);
          if (!strstr( extString, "GLX_SGIX_hyperpipe")) {

               /* Abort */
          }

          /* Create a direct rendering context and make it current */

          if (glXBindHyperpipeSGIX (dpy, hpId) {

               /* Error in bind; Abort */
          }

          /* Render */

          glXSwapBuffers(...);

          /* All done */

          glXBindHyperpipeSGIX(dpy, -1);

SEE ALSO
     glXQueryHyperpipeNetworkSGIX(), glXHyperpipeConfigSGIX(),
     glXQueryHyperpipeConfigSGIX(), glXDestroyHyperpipeConfigSGIX(),
     glXBindHyperpipeSGIX()