blob: bb7cb6f29d15469e2772d130079ec8bc323ec178 [file] [log] [blame]
Name
NV_swap_group
Name Strings
GLX_NV_swap_group
Notice
Copyright NVIDIA Corporation, 2003.
Status
Shipping since 2003 on Quadro GPUs with framelock support
Version
Date: 02/20/2008 Revision: 1.0
Number
350
Dependencies
Written based on the wording of the GLX_SGIX_swap_group and
GLX_SGIX_swap_barrier specifications.
SGIX_swap_control affects the definition of this extension
Overview
This extension provides the capability to synchronize the buffer
swaps of a group of OpenGL windows. A swap group is created, and
windows are added as members to the swap group. Buffer swaps to
members of the swap group will then take place concurrently.
This extension also provides the capability to sychronize the buffer
swaps of different swap groups, which may reside on distributed
systems on a network. For this purpose swap groups can be bound to
a swap barrier.
This extension extends the set of conditions that must be met before
a buffer swap can take place.
Issues
An implementation can not guarantee that the initialization of the swap
groups or barriers will succeed because the state of the window system may
restrict the usage of these features. Once a swap group or barrier has
been sucessfully initialized, the implementation can only guarantee to
sustain swap group functionality as long as the state of the window system
does not restrict this. An example for a state that does typically not
restrict swap group usage is the use of one fullscreen sized window per
desktop.
New Procedures and Functions
Bool glXJoinSwapGroupNV(Display *dpy,
GLXDrawable drawable,
GLuint group);
Bool glXBindSwapBarrierNV(Display *dpy,
GLuint group,
GLuint barrier);
Bool glXQuerySwapGroupNV(Display *dpy,
GLXDrawable drawable,
GLuint *group,
GLuint *barrier);
Bool glXQueryMaxSwapGroupsNV(Display *dpy,
int screen,
GLuint *maxGroups,
GLuint *maxBarriers);
Bool glXQueryFrameCountNV(Display *dpy,
int screen,
GLuint *count);
Bool glXResetFrameCountNV(Display *dpy,
int screen);
New Tokens
none
Additions to the GLX Specification
Add to section 3.2.6, Double Buffering:
glXJoinSwapGroupNV adds <drawable> to the swap group specified by
<group>. If <drawable> is already a member of a different group,
it is implicitly removed from that group first. A swap group is
specified as an integer value between 0 and the value returned in
<maxGroups> by glXQueryMaxSwapGroupsNV. If <group> is zero, the
drawable is unbound from its current group, if any. If <group> is
larger than <maxGroups>, glXJoinSwapGroupNV fails.
glXJoinSwapGroupNV returns True if <drawable> has been
successfully bound to <group> and False if it fails.
glXBindSwapBarrierNV binds the swap group specified by <group> to
<barrier>. <barrier> is an integer value between 0 and the value
returned in <maxBarriers> by glXQueryMaxSwapGroupsNV. If <barrier>
is zero, the group is unbound from its current barrier, if any. If
<barrier> is larger than <maxBarriers>, glXBindSwapBarrierNV
fails. Subsequent buffer swaps for that group will be subject to
this binding, until the group is unbound from <barrier>.
glXBindSwapBarrierNV returns True if <group> has been successfully
bound to <barrier> and False if it fails.
glXQuerySwapGroupNV returns in <group> and <barrier> the group and
barrier currently bound to <drawable,>, if any.
glXQuerySwapGroupNV returns True if <group> and <barrier> could be
successfully queried for <drawable> and False if it fails. If it
fails, the values of <group> and <barrier> are undefined.
glXQueryMaxSwapGroupsNV returns in <maxGroups> and <maxBarriers>
the maximum number of swap groups and barriers supported by an
implementation which drives <screen> and <dpy>.
glXQueryMaxSwapGroupsNV returns True if <maxGroups> and <maxBarriers>
could be successfully queried for <screen> and <dpy>, and False if
it fails. If it fails, the values of <maxGroups> and <maxBarriers>
are undefined.
Before a buffer swap can take place, a set of conditions must be
satisfied. The conditions are defined in terms of the notions of
when a drawable is ready to swap and when a group is ready to swap.
GLX drawables except windows are always ready to swap.
When a window is unmapped, it is always ready.
A window is ready when all of the following are true:
1. A buffer swap command has been issued for it.
2. Its swap interval has elapsed.
A group is ready when the following is true:
1. All windows in the group are ready.
All of the following must be satisfied before a buffer swap for a
window can take place:
1. The window is ready.
2. If the window belongs to a group, the group is ready.
3. If the window belongs to a group and that group is bound to a
barrier, all groups using that barrier are ready.
Buffer swaps for all windows in a swap group will take place
concurrently after the conditions are satisfied for every window in
the group.
Buffer swaps for all groups using a barrier will take place
concurrently after the conditions are satisfied for every window of
every group using the barrier, if and only if the vertical retraces
of the screens of all the groups are synchronized. If they are not
synchronized, there is no guarantee of concurrency between groups.
An implementation may support a limited number of swap groups and
barriers, and may have restrictions on where the users of a barrier
can reside. For example, an implementation may allow the users to
reside on different display devices or even hosts.
An implementation may return zero for any of <maxGroups> and
<maxBarriers> returned by glXQueryMaxSwapGroupsNV if swap groups or
barriers are not available in that implementation or on that host.
The implementation provides a universal counter, the so called
frame counter, among all systems that are locked together by swap
groups/barriers. It is based on the internal synchronization
signal which triggers the buffer swap.
glXQueryFrameCountNV returns in <count> the current frame counter
for <swapGroup>.
glXQueryFrameCountNV returns TRUE if the frame counter could be
successfully retrieved. Otherwise it returns FALSE.
glXResetFrameCountNV resets the frame counter of <swapGroup> to zero.
glXResetFrameCountNV returns TRUE if the frame counter could be
successfully reset, otherwise it returns FALSE. In a system that
has an NVIDIA framelock add-on adapter installed and enabled,
glXResetFrameCountNV will only succeed when the framelock is
configured as a Master system.
glXJoinSwapGroupNV, glXBindSwapBarrierNV, glXQuerySwapGroupNV,
glXQueryMaxSwapGroupsNV, glXQueryFrameCountNV and
glXResetFrameCountNV are part of the X stream.
Errors
glXJoinSwapGroupNV, glXQuerySwapGroupNV and glXQueryMaxSwapGroupsNV
generate GLXBadDrawable if <drawable> is an invalid GLX drawable.
New State
None
New Implementation Dependent State
None