blob: 69346f364ba12fbf591ba20b93dd062c500c10f8 [file] [log] [blame]
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