xref: /third_party/openGLES/extensions/NV/GLX_NV_swap_group.txt

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