xref: /third_party/openGLES/extensions/EXT/GLX_EXT_stereo_tree.txt

Name

    EXT_stereo_tree

Name Strings

    GLX_EXT_stereo_tree

Contributors

    Andy Ritger
    Arthur Huillet
    Owen Taylor

Contact

    James Jones, NVIDIA, jajones at nvidia.com

Status

    Complete

Version

    1

Number

    OpenGL Extension #452

Dependencies

    This specification is written against the wording of the GLX 1.4
    Specification.

    A minimum of GLX 1.3, or GLX 1.2 with the GLX_SGIX_pbuffer
    extension is required.

    GLX_SGIX_pbuffer affects the definition of this extension.

    The X Generic Event extension affects the definition of this
    extension.

Overview

    When using stereoscopic rendering with the X composite extension,
    a stereo-aware GLX composite manager can be used to composite both
    the left and right buffers of a window's backing pixmap to
    the left and right buffers of the root or composite overlay window
    to preserve the stereo effect of a redirected window or any of its
    child windows.  However, to do this, the composite manager needs a
    method to determine which windows have both left and right buffers
    available without needing to walk entire window trees or be aware
    of other clients' GLX drawables.

    This extension provides a new drawable tree query, which can be
    used by the composite manager when it begins tracking a window,
    and an event, which can be used to listen for updates to a tracked
    window.  This query and event provide the composite manager with a
    boolean value representing the stereo status of an entire
    redirected window tree.  With this information, the composite
    manager is able to properly choose between a stereoscopic or
    monoscopic format when creating a GLXPixmap for a given window
    tree's backing pixmap.

IP Status

    There are no known IP issues.

New Types

    typedef struct {
        int type;
        unsigned long serial;
        Bool send_event;
        Display *display;
        int extension;
        int evtype;
        GLXDrawable window;
        Bool stereo_tree;
    } GLXStereoNotifyEventEXT;

New Procedures and Functions

    None

New Tokens

    Accepted by the <attribute> parameter of glXQueryDrawable and
    glXQueryGLXPbufferSGIX:

        GLX_STEREO_TREE_EXT                   0x20F5
    
    Accepted in the <event_mask> parameter of glXSelectEvent and
    glXSelectEventSGIX, and returned in the <event_mask> parameter
    of glXGetSelectedEvent and glXGetSelectedEventSGIX:

        GLX_STEREO_NOTIFY_MASK_EXT            0x00000001

    Returned in the <evtype> field of XGenericEventCookie events:

        GLX_STEREO_NOTIFY_EXT                 0x00000000

Additions to the GLX 1.4 Specification

    [Modify Section 3.3.6, Querying Attributes]

    [Replace the 2nd sentence of the 1st paragraph with the following]
    
    "<attribute> must be set to one of GLX_WIDTH, GLX_HEIGHT,
    GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID, or
    GLX_STEREO_TREE_EXT"

    [Add the following paragraph just before the last of the section]

    "If <attribute> is GLX_STEREO_TREE_EXT and <draw> is an X Window
    or a GLXWindow, <value> will be True if <draw> is the top-level
    window of a redirected window tree and one or more windows in the
    tree are associated with a stereo GLXFBConfig.  Otherwise, <value>
    will be False."

    [Add the following to the end of the section]

    "If <draw> is not a GLXWindow or X Window and <attribute> is set
    to GLX_STEREO_TREE_EXT, then the contents of <value> are
    undefined."

    [Modify Section 3.3.8, Events]

    [Replace the 3rd-5th paragraphs with the following]

    "If <draw> is not a valid GLXPbuffer, GLXWindow, or X Window, a
    GLXBadDrawable error is generated.

    "To find out which GLX events are selected for a GLXWindow,
    GLXPbuffer, or X Window call

        void glXGetSelectedEvent(Display *dpy, GLXDrawable draw,
                                 unsigned long *event_mask);

    "If <draw> is not a GLX window or pbuffer, or an X window,
    GLXBadDrawable is generated.

    "Currently there are two GLX events that can be selected, by
    setting <event_mask> to GLX_PBUFFER_CLOBBER_MASK or
    GLX_STEREO_NOTIFY_MASK_EXT.  The data structure describing a
    pbuffer clobber event is:"

    [Add the following at the end of the section]

    "stereo notify events are delivered using the generic event
    extension when a redirected window or one of its children sharing
    the same backing pixmap is associated or disassociated with a
    stereo GLXFBConfig.  The data structure describing a stereo notify
    event is:

        typedef struct {
            int type; /* GenericEvent */
            unsigned long serial; /* # of last request server processed */
            Bool send_event; /* True if generated by SendEvent request */
            Display *display; /* display the event was read from */
            int extension; /* GLX major opcode, from XQueryExtension */
            int evtype; /* always GLX_STEREO_NOTIFY_EXT */
            GLXDrawable window; /* XID of the X window affected */
            Bool stereo_tree; /* True if tree contains stereo windows */
        } GLXStereoNotifyEventEXT;

    "If an implementation doesn't support stereo rendering with the
    X composite extension, then it does not need to support the
    generation of GLXStereoNotifyEventEXT events.

    "If <stereo_tree> is True, <window> is the top-level window in a
    redirected window tree that contains at least one stereo GLX
    window drawable.  Otherwise, <stereo_tree> will be False.

    "No GLXStereoNotifyEventEXT events will be generated for the root
    window or composite overlay window, since they can not be
    redirected.

    "The value of <window> will refer to an X window, regardless of
    whether a GLXWindow or an X window id was passed to
    glXSelectEvent"

GLX Protocol

    One new generic event is added:

        MOC is the major opcode for the extension, as returned by
        XQueryExtension.

        GLX_STEREO_NOTIFY_EXT
            1        35 (GenericEvent) type
            1        MOC               extension
            2        CARD16            sequence_number
            4        0                 length
            2        CARD16            evtype
                     0x00000000        GLX_STEREO_NOTIFY_EXT
            1        BYTE              stereo_tree
            1                          unused
            4        GLX_DRAWABLE      window
            16                         unused

Dependencies on GLX_SGIX_pbuffer

    If GLX_SGIX_pbuffer is not present, the references to
    glXSelectEventSGIX and glXGetSelectedEventSGIX are removed.

Dependencies on the X Generic Event extension

    If the generic event extension is not present, the events
    specified here will not be delivered.

Errors

    None

Issues

    1)  Does the language describing which drawable types
        glXQueryDrawable accepts need to be extended to include X
        windows?

        RESOLVED: No.  GLXDrawable is already defined to include X
        windows by the GLX protocol specification.

    2)  Should the events and queries added here work on non-
        redirected window trees, or the root window as well?

        RESOLVED: No.  Implementations may not need to track such
        information for these types of windows, so it would add burden
        with no apparent benefit to applications.  Consequently, the
        queries will always return False and no events will be
        generated for these windows.

    3)  Should a GLX extension event or a generic event be used for
        the new stereo notification mechanism?

        RESOLVED: A generic event should be used.  Adding extension
        events to existing extensions has been shown to be problematic
        when updated servers are mixed with older clients, and modern
        X server implementations are running out of extension event
        slots.

Version History

    1.  06 Mar 2014
        - Initial Draft