1Name 2 3 EXT_stereo_tree 4 5Name Strings 6 7 GLX_EXT_stereo_tree 8 9Contributors 10 11 Andy Ritger 12 Arthur Huillet 13 Owen Taylor 14 15Contact 16 17 James Jones, NVIDIA, jajones at nvidia.com 18 19Status 20 21 Complete 22 23Version 24 25 1 26 27Number 28 29 OpenGL Extension #452 30 31Dependencies 32 33 This specification is written against the wording of the GLX 1.4 34 Specification. 35 36 A minimum of GLX 1.3, or GLX 1.2 with the GLX_SGIX_pbuffer 37 extension is required. 38 39 GLX_SGIX_pbuffer affects the definition of this extension. 40 41 The X Generic Event extension affects the definition of this 42 extension. 43 44Overview 45 46 When using stereoscopic rendering with the X composite extension, 47 a stereo-aware GLX composite manager can be used to composite both 48 the left and right buffers of a window's backing pixmap to 49 the left and right buffers of the root or composite overlay window 50 to preserve the stereo effect of a redirected window or any of its 51 child windows. However, to do this, the composite manager needs a 52 method to determine which windows have both left and right buffers 53 available without needing to walk entire window trees or be aware 54 of other clients' GLX drawables. 55 56 This extension provides a new drawable tree query, which can be 57 used by the composite manager when it begins tracking a window, 58 and an event, which can be used to listen for updates to a tracked 59 window. This query and event provide the composite manager with a 60 boolean value representing the stereo status of an entire 61 redirected window tree. With this information, the composite 62 manager is able to properly choose between a stereoscopic or 63 monoscopic format when creating a GLXPixmap for a given window 64 tree's backing pixmap. 65 66IP Status 67 68 There are no known IP issues. 69 70New Types 71 72 typedef struct { 73 int type; 74 unsigned long serial; 75 Bool send_event; 76 Display *display; 77 int extension; 78 int evtype; 79 GLXDrawable window; 80 Bool stereo_tree; 81 } GLXStereoNotifyEventEXT; 82 83New Procedures and Functions 84 85 None 86 87New Tokens 88 89 Accepted by the <attribute> parameter of glXQueryDrawable and 90 glXQueryGLXPbufferSGIX: 91 92 GLX_STEREO_TREE_EXT 0x20F5 93 94 Accepted in the <event_mask> parameter of glXSelectEvent and 95 glXSelectEventSGIX, and returned in the <event_mask> parameter 96 of glXGetSelectedEvent and glXGetSelectedEventSGIX: 97 98 GLX_STEREO_NOTIFY_MASK_EXT 0x00000001 99 100 Returned in the <evtype> field of XGenericEventCookie events: 101 102 GLX_STEREO_NOTIFY_EXT 0x00000000 103 104Additions to the GLX 1.4 Specification 105 106 [Modify Section 3.3.6, Querying Attributes] 107 108 [Replace the 2nd sentence of the 1st paragraph with the following] 109 110 "<attribute> must be set to one of GLX_WIDTH, GLX_HEIGHT, 111 GLX_PRESERVED_CONTENTS, GLX_LARGEST_PBUFFER, GLX_FBCONFIG_ID, or 112 GLX_STEREO_TREE_EXT" 113 114 [Add the following paragraph just before the last of the section] 115 116 "If <attribute> is GLX_STEREO_TREE_EXT and <draw> is an X Window 117 or a GLXWindow, <value> will be True if <draw> is the top-level 118 window of a redirected window tree and one or more windows in the 119 tree are associated with a stereo GLXFBConfig. Otherwise, <value> 120 will be False." 121 122 [Add the following to the end of the section] 123 124 "If <draw> is not a GLXWindow or X Window and <attribute> is set 125 to GLX_STEREO_TREE_EXT, then the contents of <value> are 126 undefined." 127 128 [Modify Section 3.3.8, Events] 129 130 [Replace the 3rd-5th paragraphs with the following] 131 132 "If <draw> is not a valid GLXPbuffer, GLXWindow, or X Window, a 133 GLXBadDrawable error is generated. 134 135 "To find out which GLX events are selected for a GLXWindow, 136 GLXPbuffer, or X Window call 137 138 void glXGetSelectedEvent(Display *dpy, GLXDrawable draw, 139 unsigned long *event_mask); 140 141 "If <draw> is not a GLX window or pbuffer, or an X window, 142 GLXBadDrawable is generated. 143 144 "Currently there are two GLX events that can be selected, by 145 setting <event_mask> to GLX_PBUFFER_CLOBBER_MASK or 146 GLX_STEREO_NOTIFY_MASK_EXT. The data structure describing a 147 pbuffer clobber event is:" 148 149 [Add the following at the end of the section] 150 151 "stereo notify events are delivered using the generic event 152 extension when a redirected window or one of its children sharing 153 the same backing pixmap is associated or disassociated with a 154 stereo GLXFBConfig. The data structure describing a stereo notify 155 event is: 156 157 typedef struct { 158 int type; /* GenericEvent */ 159 unsigned long serial; /* # of last request server processed */ 160 Bool send_event; /* True if generated by SendEvent request */ 161 Display *display; /* display the event was read from */ 162 int extension; /* GLX major opcode, from XQueryExtension */ 163 int evtype; /* always GLX_STEREO_NOTIFY_EXT */ 164 GLXDrawable window; /* XID of the X window affected */ 165 Bool stereo_tree; /* True if tree contains stereo windows */ 166 } GLXStereoNotifyEventEXT; 167 168 "If an implementation doesn't support stereo rendering with the 169 X composite extension, then it does not need to support the 170 generation of GLXStereoNotifyEventEXT events. 171 172 "If <stereo_tree> is True, <window> is the top-level window in a 173 redirected window tree that contains at least one stereo GLX 174 window drawable. Otherwise, <stereo_tree> will be False. 175 176 "No GLXStereoNotifyEventEXT events will be generated for the root 177 window or composite overlay window, since they can not be 178 redirected. 179 180 "The value of <window> will refer to an X window, regardless of 181 whether a GLXWindow or an X window id was passed to 182 glXSelectEvent" 183 184GLX Protocol 185 186 One new generic event is added: 187 188 MOC is the major opcode for the extension, as returned by 189 XQueryExtension. 190 191 GLX_STEREO_NOTIFY_EXT 192 1 35 (GenericEvent) type 193 1 MOC extension 194 2 CARD16 sequence_number 195 4 0 length 196 2 CARD16 evtype 197 0x00000000 GLX_STEREO_NOTIFY_EXT 198 1 BYTE stereo_tree 199 1 unused 200 4 GLX_DRAWABLE window 201 16 unused 202 203Dependencies on GLX_SGIX_pbuffer 204 205 If GLX_SGIX_pbuffer is not present, the references to 206 glXSelectEventSGIX and glXGetSelectedEventSGIX are removed. 207 208Dependencies on the X Generic Event extension 209 210 If the generic event extension is not present, the events 211 specified here will not be delivered. 212 213Errors 214 215 None 216 217Issues 218 219 1) Does the language describing which drawable types 220 glXQueryDrawable accepts need to be extended to include X 221 windows? 222 223 RESOLVED: No. GLXDrawable is already defined to include X 224 windows by the GLX protocol specification. 225 226 2) Should the events and queries added here work on non- 227 redirected window trees, or the root window as well? 228 229 RESOLVED: No. Implementations may not need to track such 230 information for these types of windows, so it would add burden 231 with no apparent benefit to applications. Consequently, the 232 queries will always return False and no events will be 233 generated for these windows. 234 235 3) Should a GLX extension event or a generic event be used for 236 the new stereo notification mechanism? 237 238 RESOLVED: A generic event should be used. Adding extension 239 events to existing extensions has been shown to be problematic 240 when updated servers are mixed with older clients, and modern 241 X server implementations are running out of extension event 242 slots. 243 244Version History 245 246 1. 06 Mar 2014 247 - Initial Draft 248