Back to the OpenGL extension cross reference
GLX_SGIX_hyperpipe
SGIX_hyperpipe
Name Strings
GLX_SGIX_hyperpipe
Contact
Jon Leech, SGI (ljp 'at' sgi.com)
Status
Shipping on SGI Infinite Reality and Ultimate Vision systems.
Version
Last Modified Date: 2004/07/21
Revision: $Header: //depot/main/doc/registry/extensions/SGI/hyperpipe_group.spec#14 $
Number
307
Dependencies
GLX 1.2 is required
SGIX_swap_control affects the definition of this extension.
Overview
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 multithreaded, 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.
Issues and Notes
o This extension will work only on graphics pipelines with suitable
hyperpipe hardware installed.
The following structure definitions are used by the extension:
/*
* pipeName uniquely names a pipe in the form ":display.screen"
* networkId is a unique physical hyperpipe network ID.
*/
typedef struct {
char pipeName[GLX_HYPERPIPE_PIPE_NAME_LENGTH_SGIX];
int networkId;
} GLXHyperpipeNetworkSGIX;
/*
* pipeName uniquely names a pipe in the form ":display.screen"
* channel is the channel number associated with the display pipe.
* participationType is a bitmask describing the attributes of a
* participating pipe. It may contain one or more of the
* attribute bits
* GLX_HYPERPIPE_DISPLAY_PIPE_SGIX
* GLX_HYPERPIPE_RENDERING_PIPE_SGIX
* timeSlice is ignored for GLX_HYPERPIPE_DISPLAY_PIPE_SGIX only.
*/
typedef struct {
char pipeName[GLX_HYPERPIPE_PIPE_NAME_LENGTH_SGIX];
int channel;
unsigned int participationType;
int timeSlice;
} GLXHyperpipeConfigSGIX;
/*
* pipeName uniquely names a pipe in the form ":display.screen"
* src origin/size are in managed area coordinates (pixels).
* dest origin/size are in output channel display coordinates.
*/
typedef struct {
char pipeName[GLX_HYPERPIPE_PIPE_NAME_LENGTH_SGIX];
int srcXOrigin;
int srcYOrigin;
int srcWidth;
int srcHeight;
int destXOrigin;
int destYOrigin;
int destWidth;
int destHeight;
} GLXPipeRect;
/*
* pipeName uniquely names a pipe in the form ":display.screen"
* origin/size are in managed area coordinates (pixels)
*/
typedef struct {
char pipeName[GLX_HYPERPIPE_PIPE_NAME_LENGTH_SGIX];
int XOrigin; /* pixels in managed area */
int YOrigin;
int maxHeight;
int maxWidth;
} GLXPipeRectLimits;
GLXHyperpipeNetworkSGIX *
glXQueryHyperpipeNetworkSGIX(
Display *dpy, int *npipes);
int glXHyperpipeConfigSGIX(
Display *dpy, int networkId, int npipes,
GLXHyperpipeConfigSGIX *cfg, int *hpId);
GLXHyperpipeConfigSGIX *
glXQueryHyperpipeConfigSGIX(
Display *dpy, int hpId, int *npipes);
int glXDestroyHyperpipeConfigSGIX(
Display * dpy, int hpId);
int glXBindHyperpipeSGIX(
Display *dpy, int hpId);
int glXQueryHyperpipeBestAttribSGIX(
Display *dpy, int timeSlice, int attrib, int size,
void *attribList, void *returnAttribList);
int glXHyperpipeAttribSGIX(
Display *dpy, int timeSlice, int attrib, int size,
void *attribList);
int glXQueryHyperpipeAttribSGIX(
Display *dpy, int timeSlice, int attrib, int size,
void *returnAttribList);
Accepted by the <attribute> parameter of glXQueryContextInfoEXT:
GLX_HYPERPIPE_ID_SGIX 0x8030
Maximum length of the string naming a hyperpipe:
GLX_HYPERPIPE_PIPE_NAME_LENGTH_SGIX 80
Bits that may be set in the <participationType> bitfield of the
GLXHyperpipeConfigSGIX argument passed into glXHyperpipeConfigSGIX
and returned by glXQueryHyperpipeConfigSGIX:
GLX_HYPERPIPE_DISPLAY_PIPE_SGIX 0x00000001
GLX_HYPERPIPE_RENDER_PIPE_SGIX 0x00000002
Accepted by the <attrib> parameter of glXQueryHyperpipeAttribSGIX:
GLX_PIPE_RECT_SGIX 0x00000001
GLX_PIPE_RECT_LIMITS_SGIX 0x00000002
GLX_HYPERPIPE_STEREO_SGIX 0x00000003
GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX 0x00000004
Accepted by the <attrib> parameters of and glXHyperpipeAttribSGIX:
GLX_PIPE_RECT_SGIX
GLX_HYPERPIPE_STEREO_SGIX
GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX
Accepted by the <attrib> parameter of
glXQueryHyperpipeBestAttribSGIX:
GLX_PIPE_RECT_SGIX
GLX_PIPE_RECT_LIMITS_SGIX
New error codes:
GLX_BAD_HYPERPIPE_CONFIG_SGIX 91
GLX_BAD_HYPERPIPE_SGIX 92
Additions to the GLX 1.3 Specification
Add new section 3.X "Hyperpipes"
Hyperpipes are collections of graphics pipes that may operate
together to generate images. The pipes may be split either spatially
(with different pipes rendering different subrectangles of an output
image), temporally (with different pipes rendering different time
slices of an output image), or both.
Section 3.X.1 "Hyperpipe Networks"
To determine the physical connectivity of hyperpipes in a system,
call
GLXHyperpipeNetworkSGIX *glXQueryHyperpipeNetworkSGIX(
Display *dpy, int *npipes)
There may be more than one hyperpipe network in the system. The
networks are numbered sequentially.
glXQueryHyperpipeNetworkSGIX returns a pointer to an array of
GLXHyperpipeNetworkSGIX structures describing the availalable pipes.
This list is sorted on the physical hyperpipe network number (the
<networkId> field of the GLXHyperpipeNetworkSGIX structure).
Networks are numbered sequentially from 0.
The number of pipes is returned in <*npipes>. If no hyperpipe
network is defined in the system, NULL is returned. returns NULL.
Use XFree to free the array returned by
glXQueryHyperpipeNetworkSGIX.
Section 3.X.2 "Hyperpipe Configuration"
To specify the logical configuration of a hyperpipe, call
int glXHyperpipeConfigSGIX(Display *dpy, int networkId,
int npipes, GLXHyperpipeConfigSGIX *cfg, int *hpId);
The physical connectivity of a hyperpipe is determined by the
cabling of the hardware. It is possible to use only a subset of the
pipes physically connected together. These participant pipes may
contribute to the hyperpipe in a temporally interleaved manner
and/or spatially subdivided manner. The configuration information
specifies which pipes participate in the hyperpipe. It also
specifies the relative order of these pipes and their type of
contribution (spatial or temporal). This configuration cannot be
arbitrary and is subject to some hardware constraints.
<networkId> specifies the physical hyperpipe network ID to be
configured. <npipes> specifies the total number of pipes in the
configuration. <cfg> is a pointer to an array of <npipes>
GLXHyperpipeConfigSGIX structures, each specifying the configuration
for a single pipe.
The <pipeName> field of each <cfg> structure specifies the pipe ID
of that pipe, and the <channel> field specifies a channel number
associated with that pipe.
If the <participationType> field contains
GLX_HYPERPIPE_RENDER_PIPE_SGIX, the pipe is designated to render
data for a subset of the pipeline (spatially or temporally). If the
field contains GLX_HYPERPIPE_DISPLAY_PIPE_SGIX, the pipe is
designated to assemble rendered data and display it on that pipe's
local channel. There can be multiple rendering pipes, but only one
display pipe in a network.
The <timeSlice> field specifies the time slice to which a rendering
pipe contributes, and must be in the range 0 to <npipes>-1.
On success, a unique hyperpipe ID is generated and returned in the
integer pointed to by <hpId>. Subsequent calls may require a valid
hyperpipe ID parameter. In the case of a multi-process application,
the master process should configure the hyperpipe, and child
processes should then use the same hyperpipe ID as the master
process. The hyperpipe ID is global across multiple processes. If
another process attempts a configuration using already allocated
pipes, the second configuration will fail.
If the pipes contribute in a spatially subdivided manner, then the
screen is divided evenly between them. This division can be
subsequently changed via calls to glXHyperpipeAttribSGIX().
glXHyperpipeConfigSGIX() returns GLX_BAD_HYPERPIPE_CONFIG_SGIX if
the specified <cfg> is invalid.
To query the details of a hyperpipe configuration, call
GLXHyperpipeConfigSGIX *glXQueryHyperpipeConfigSGIX(
Display *dpy, int hpId, int *npipes);
<hpId> is the ID of the hyperpipe configuration to query. It must
have been obtained from a previous call to glXHyperpipeConfigSGIX.
glXQueryHyperpipeConfigSGIX returns a pointer to an array of
GLXHyperpipeConfigSGIX structures describing the pipes in the
configuration. The parameters of the structures are as described for
glXHyperpipeConfigSGIX.
The number of pipes is returned in <*npipes>. If <hpId> is not a
valid hyperpipe ID, NULL is returned. Use XFree to free the array
returned by glXQueryHyperpipeConfigSGIX.
To destroy a hyperpipe configuration, call
int glXDestroyHyperpipeConfigSGIX(Display * dpy, int hpId);
<hpId> is the ID of the hyperpipe configuration to destroy. It must
have been obtained from a previous call to glXHyperpipeConfigSGIX.
All process should unbind from <hpId> by calling
glXBindHyperipipeSGIX(dpy, -1) before destroying the hyperpipe
configuration.
On success, the resources associated with <hpId> are destroyed and
<hpId> is no longer a valid hyperpipe ID.
glXHyperpipeConfigSGIX() returns GLX_BAD_HYPERPIPE_SGIX if there is
no valid hyperpipe configuration with the specified ID.
Section 3.X.2 "Binding Hyperpipes"
To bind the current rendering context to a hyperpipe, call
int glXBindHyperpipeSGIX(Display *dpy, int hpId);
This establishes an association between the calling process, the
current context, and the hyperpipe configuration with ID <hpId>.
When this rendering context is destroyed, the hyperpipe operations
associated with this hyperpipe group may be terminated.
Every process participating in a hyperpipe should call
glXBindHyperpipeSGIX after creating and choosing a rendering
context. Hyperpipe requests to this process will not begin until
this call is made.
It is possible to determine if a hyperpipe is bound by calling
glXQueryContextInfoEXT with the attribute GLX_HYPERPIPE_ID_SGIX.
Calling glXBindHyperpipeSGIX with <hpId> == -1 unbinds the current
rendering context from the hyperpipe. If no hyperpipe is bound, this
call is ignored and no error is generated.
A process can bind to only one hyperpipe at any time. In order to
bind to another hyperpipe, the process must explicitly unbind from
the current hyperpipe. If a process calls glXBindHyperpipeSGIX()
more than once without an intervening unbind, then the subsequent
bind will fail.
glXBindHyperpipeSGIX returns GLX_BAD_HYPERPIPE_SGIX if <hpId> is not
a valid hyperpipe ID.
To determine the best possible hyperpipe attributes subject to
constraints imposed by the hyperpipe implementation, call
int glXQueryHyperpipeBestAttribSGIX(Display *dpy,
int timeSlice, int attrib, int size, void *attribList,
void *returnAttribList);
<timeSlice> specifies the time slice for which <attrib> is queried.
Its value may range from 0 to the maximum number of time slices for
which the hyperpipe is configure.
<attrib> is a bitmask specifying the type of the attribute for which
the best attributes are to be determined.
<size> specifies the total size, in bytes, of the arrays pointed to
by <attribList> and <returnAttribList>.
<attribList> is a pointer to an array of requested values. The array
contains one value, of type determined by <attrib>, for each pipe
contributing to the specified time slice.
<returnAttribList> is a pointer to an array in which returned values
are copied. The array must be large enough to contain one value, of
type determined by <attrib>, for each pipe contributing to the
specified time slice (in other words, must be the same size as the
array pointed to by <attribList>). Values returned will be as close
as possible to those specified in <attribList>, subject to the
implementation constraints.
If <attrib> is GLX_PIPE_RECT, the subrectangles composing a
hyperpipe rectangle during <timeSlice> are queried. <attribList>
must point to an array of <n> GLXPipeRect structures, one for each
pipe contributing to the specified <timeSlice> of the currently
bound hyperpipe, each defining an input source rectangle (origin,
width, and height in the managed area), and an output destination
rectangle (origin, width, and height in the output display area). In
this case <size> must be <n> * sizeof(GLXPipeRect).
If <attrib> is GLX_PIPE_RECT_LIMITS, the maximum size of the
subrectangles during <timeSlice> are queried. <attribList> must
point to an array of <n> GLXPipeRectLimits structures, each defining
an origin and maximum width and height in the managed area. In this
case <size> must be <n> * sizeof(GLXPipeRectLimits), where <n> is
the number of pipes participating in <timeSlice>.
glXQueryHyperpipeBestAttribSGIX returns GLX_BAD_HYPERPIPE_SGIX if
there is no valid hyperpipe configuration bound to the current
context, or if <size> is too small for the amount of data
implied by <timeSlice> and <attrib>.
glXQueryHypepipeBestAttribSGIX returns GLX_BAD_VALUE if <attrib> is
not one of GLX_PIPE_RECT or GLX_PIPE_RECT_LIMITS, or if any of the
elements in <attribList> cannot be altered to satisfy the
constraints of the current hyperpipe.
Section 3.X.3 "Hyperpipe Attributes"
To set hyperpipe attribute values, call
int glXHyperpipeAttribSGIX(Display *dpy, int timeSlice,
int attrib, int size, void *attribList);
<timeSlice>, <attrib>, and <size> have the same meaning as the
corresponding attributes of glXQueryHyperpipeBestAttribSGIX.
If <attrib> is GLX_PIPE_RECT_SGIX, <attribList> must point to an
array of <n> subrectangles defined by GLXPipeRect structures, one for
each pipe contributing to the specified <timeSlice> of the currently
bound hyperpipe. This allows load balancing the pipes. In this case
<size> must be <n> * sizeof(GLXPipeRect).
If <attrib> is GLX_HYPERPIPE_STEREO_SGIX, <attribList> must point to
an integer controlling alternation between pipes in the hyerpipe.
One pipe provides the left eye data, and the second provides the
right eye data. An attribute value of 1 enables stereo for the
corresponding pipe, and an attribute value of 0 disables stereo. In
this case <size> = sizeof(int).
If <attrib> is GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX, <attribList> must
point to an integer controlling averaging of pixel data. An
attribute value of 1 enables an averaging mode in which
corresponding pixel values from all pipes in the hyperpipe are
averaged together before being sent to the display, and an attribute
value of 0 disables averaging. In this case <size> = sizeof(int).
glXHyperpipeAttribSGIX is swap synchronous; that is, the attributes
are not changed until glXSwapBuffers is called for the corresponding
window.
glXHyperpipeAttribSGIX returns GLX_BAD_HYPERPIPE_SGIX if there is no
valid hyperpipe configuration bound to the current context, or if
<size> is too small for the amount of data implied by <timeSlice>
and <attrib>.
glXHypepipeAttribSGIX returns GLX_BAD_VALUE if <attrib> is not one
of GLX_PIPE_RECT_SGIX, GLX_HYPERPIPE_STEREO_SGIX, or
GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX.
To query hyperpipe attribute values, call
int glXQueryHyperpipeAttribSGIX(Display *dpy, int timeSlice,
int attrib, int size, void *returnAttribList);
<timeSlice>, <attrib>, and <size> have the same meaning as the
corresponding attributes of glXHyperpipeAttribSGIX.
If <attrib> is GLX_PIPE_RECT_SGIX, <attribList> must point to an
array of <n> GLXPipeRect structures, one for each pipe contributing
to the specified <timeSlice> of the currently bound hyperpipe. The
subrectangles corresponding to each pipe are returned in
<attribList>. In this case <size> must be <n> * sizeof(GLXPipeRect).
If <attrib> is GLX_PIPE_RECT_LIMITS_SGIX, <attribList> must point to
an array of <n> GLXPipeRectLimits structures, one for each pipe
contributing to the specified <timeSlice> of the currently bound
hyperpipe. The maximum width and height of the subrectangles
corresponding to each pipe are returned in <attribList>. In this
case <size> must be <n> * sizeof(GLXPipeRectLimits).
If <attrib> is GLX_HYPERPIPE_STEREO_SGIX, <attribList> must point to
an integer. A return value of 1 indicates that stereo is enabled
while a return value of 0 indicates that stereo is disabled. In this
case <size> = sizeof(int).
If <attrib> is GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX, <attribList> must
point to an integer. A return value of 1 indicates that pixel
averaging is enabled, while a return value of 0 indicates that pixel
averaging is disabled. In this case <size> = sizeof(int).
glXQueryHyperpipeAttribSGIX returns GLX_BAD_HYPERPIPE_SGIX if there
is no valid hyperpipe configuration bound to the current context, or
if <size> is too small for the amount of data implied by <timeSlice>
and <attrib>.
glXQueryHypepipeAttribSGIX returns GLX_BAD_VALUE if <attrib> is not
one of GLX_PIPE_RECT_SGIX, GLX_PIPE_RECT_LIMITS_SGIX,
GLX_HYPERPIPE_STEREO_SGIX, or GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX.
Add to section 3.2.6, Double Buffering:
When a hyperpipe is bound to the current context, all pipes
participating in a single time slice will swap together.
glXSwapBuffers may be called even for a single-buffered visual when
a hyperpipe is bound, to cause the hyperpipe to switch to the next
time slice.
When a pipe in a hyperpipe configuration completes rendering of its
portion of the framebuffer, completion is indicated by via a call to
glXSwapBuffers. After all the pipes contributing to a particular
time slice indicate completion, the hyperpipe requests for this time
slice may begin.
[Add to table listing GLX context attributes for glXQueryContextInfoEXT]
GLX context attribute type context information
--------------------- ---- -------------------
GLX_HYPERPIPE_ID_SGIX XID hyperpipe id, if the rendering context
is associated with a hyperpipe
Errors
Errors specific to hyperpipes are defined in the specification
language. GLX_BAD_CONTEXT may be returned by any hyperpipe call if
there is no valid current context.
Implementation Notes
glXQueryHyperpipeBestAttribSGIX and glXHyperpipeAttribSGIX are
currently supported only on InfinitePerformance systems.
On InfinitePerformance systems, GLX_PIPE_RECT_SGIX requires that X
origins and sizes be aligned on 4 pixel boundaries.
The hyperpipe context ensures that resize parameters may be
synchronized across a hyperpipe. The details of this synchronization
are system-dependent, and may for example use the /dev/gfx device on
SGI IRIX systems.
In SGI implementations using external compositors (e.g. SG2), the
distinction between display and render pipes in the
<participationType> bitfield is ignored. In principle both bits
could be set for a single pipe, but no implementations in which this
mode is supported, or makes sense, have yet been developed.
In SGI implementations, the pixel averaging mode controlled by
GLX_HYPERPIPE_PIXEL_AVERAGE_SGIX is meant to be used for full-screen
antialiasing, with each pipe in a time slice contributing jittered
samples for each pixel in the output image.
The SGI implementation uses an internal constant
GLX_HYPERPIPE_PIPE_NPIPES_SGIX = 32. This token is not exposed in
the external API, and has not been placed in the public glxext.h
header file.
Revision History
Revision 14, 2004/07/22 - closed out some open issues based on the
SGI implementation details.
Revision 13, 2004/07/21 - completely rewrote specification based on
the IRIX man pages. This should be substantially more complete than
the previous (1999) revision, and better correspond to what's
actually being shipped.
Implementation Support
List of OpenGL implementations supporting the GLX_SGIX_hyperpipe extension
Original File
Original text file for the GLX_SGIX_hyperpipe extension
Page generated on Sun Nov 20 18:38:50 2005