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 parameter of glXQueryDrawable and glXQueryGLXPbufferSGIX: GLX_STEREO_TREE_EXT 0x20F5 Accepted in the parameter of glXSelectEvent and glXSelectEventSGIX, and returned in the parameter of glXGetSelectedEvent and glXGetSelectedEventSGIX: GLX_STEREO_NOTIFY_MASK_EXT 0x00000001 Returned in the 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] " 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 is GLX_STEREO_TREE_EXT and is an X Window or a GLXWindow, will be True if 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, will be False." [Add the following to the end of the section] "If is not a GLXWindow or X Window and is set to GLX_STEREO_TREE_EXT, then the contents of are undefined." [Modify Section 3.3.8, Events] [Replace the 3rd-5th paragraphs with the following] "If 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 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 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 is True, is the top-level window in a redirected window tree that contains at least one stereo GLX window drawable. Otherwise, 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 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