1Name 2 3 OML_sync_control 4 5Name Strings 6 7 GLX_OML_sync_control 8 9Contact 10 11 Randi Rost, 3Dlabs (rost 'at' 3dlabs.com) 12 13Status 14 15 Complete. Approved by the Khronos SIG on July 19, 2001. 16 17Version 18 19 Last Modified Date: 07/23/2001 Revision: 6.0 20 21 Based on WGL_OML_sync_control Revision 16.0 22 23Number 24 25 238 26 27Dependencies 28 29 The extension is written against the OpenGL 1.2.1 Specification 30 and the GLX 1.3 Specification, although it should work on previous 31 versions of these specifications. 32 33Overview 34 35 This extension provides the control necessary to ensure 36 synchronization between events on the graphics card (such as 37 vertical retrace) and other parts of the system. It provides support 38 for applications with real-time rendering requirements by providing 39 precise synchronization between graphics and streaming video or 40 audio. 41 42 This extension incorporates the use of three counters that provide 43 the necessary synchronization. The Unadjusted System Time (or UST) 44 is a 64-bit monotonically increasing counter that is available 45 throughout the system. UST is not a resource that is controlled 46 by OpenGL, so it is not defined further as part of this extension. 47 The graphics Media Stream Counter (or graphics MSC) is a counter 48 that is unique to the graphics subsystem and increments for each 49 vertical retrace that occurs. The Swap Buffer Counter (SBC) is an 50 attribute of a GLXDrawable and is incremented each time a swap 51 buffer action is performed on the associated drawable. 52 53 The use of these three counters allows the application to 54 synchronize graphics rendering to vertical retraces and/or swap 55 buffer actions, and to synchronize other activities in the system 56 (such as streaming video or audio) to vertical retraces and/or 57 swap buffer actions. 58 59 Functions are provided to allow an application to detect when an 60 MSC or SBC has reached a certain value. This function will block 61 until the specified value has been reached. Applications that want 62 to continue other processing while waiting are expected to call 63 these blocking functions from a thread that is separate from the 64 main processing thread(s) of the application. 65 66 This extension carefully defines the observable order in which 67 things occur in order to allow implementations to perform 68 optimizations and avoid artifacts such as tearing, while at the 69 same time providing a framework for consistent behavior from the 70 point of view of an application. 71 72Issues 73 74 None. 75 76IP Status 77 78 No known issues. 79 80New Procedures and Functions 81 82 Bool glXGetSyncValuesOML(Display* dpy, 83 GLXDrawable drawable, 84 int64_t* ust, 85 int64_t* msc, 86 int64_t* sbc) 87 88 Bool glXGetMscRateOML(Display* dpy, 89 GLXDrawable drawable, 90 int32_t* numerator, 91 int32_t* denominator) 92 93 int64_t glXSwapBuffersMscOML(Display* dpy, 94 GLXDrawable drawable, 95 int64_t target_msc, 96 int64_t divisor, 97 int64_t remainder) 98 99 Bool glXWaitForMscOML(Display* dpy, 100 GLXDrawable drawable, 101 int64_t target_msc, 102 int64_t divisor, 103 int64_t remainder, 104 int64_t* ust, 105 int64_t* msc, 106 int64_t* sbc) 107 108 Bool glXWaitForSbcOML(Display* dpy, 109 GLXDrawable drawable, 110 int64_t target_sbc, 111 int64_t* ust, 112 int64_t* msc, 113 int64_t* sbc) 114 115New Tokens 116 117 None 118 119Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation) 120 121 None 122 123Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization) 124 125 None 126 127Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment 128Operations and the Framebuffer) 129 130 None 131 132Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions) 133 134 None 135 136Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and 137State Requests) 138 139 None 140 141Additions to the GLX 1.3 Specification 142 143 glXGetSyncValuesOML returns the current UST/MSC/SBC triple. A UST 144 timestamp is obtained each time the graphics MSC is incremented. 145 If this value does not reflect the value of the UST at the time the 146 first scan line of the display begins passing through the video 147 output port, it will be adjusted by the graphics driver to do so 148 prior to being returned by any of the functions defined by this 149 extension. 150 151 This UST timestamp, together with the current graphics MSC and the 152 current SBC, comprise the current UST/MSC/SBC triple. The UST, 153 graphics MSC, and SBC values are not part of the render context 154 state. These values cannot be pushed or popped. The graphics MSC 155 value is initialized to 0 when the graphics device is initialized. 156 The SBC is per-window state and is initialized to 0 when the 157 GLXDrawable data structure is initialized. 158 159 The SBC value is incremented by the graphics driver at the completion 160 of each buffer swap (e.g., the pixel copy has been completed or the 161 hardware register that swaps memory banks has been written). For pixel 162 formats that do not contain a back buffer, the SBC will always be 163 returned as 0. 164 165 The graphics MSC value is incremented once for each screen refresh. 166 For a non-interlaced display, this means that the graphics MSC value 167 is incremented for each frame. For an interlaced display, it means 168 that it will be incremented for each field. For a multi-monitor 169 system, the monitor used to determine MSC is screen 0 of <display>. 170 171 glXGetMscRateOML returns the rate at which the MSC will be incremented 172 for the display associated with <hdc>. The rate is expressed in Hertz 173 as <numerator> / <denominator>. If the MSC rate in Hertz is an 174 integer, then <denominator> will be 1 and <numerator> will be 175 the MSC rate. 176 177 glXSwapBuffersMscOML has the same functionality as glXSwapBuffers, 178 except for the following. The swap indicated by a call to 179 glXSwapBuffersMscOML does not perform an implicit glFlush. The 180 indicated swap will not occur until all prior rendering commands 181 affecting the buffer have been completed. Once prior rendering 182 commands have been completed, if the current MSC is less than 183 <target_msc>, the buffer swap will occur when the MSC value becomes 184 equal to <target_msc>. Once prior rendering commands have completed, 185 if the current MSC is greater than or equal to <target_msc>, the 186 buffer swap will occur the next time the MSC value is incremented 187 to a value such that MSC % <divisor> = <remainder>. If <divisor> = 0, 188 the swap will occur when MSC becomes greater than or equal to 189 <target_msc>. 190 191 Once glXSwapBuffersMscOML has been called, subsequent OpenGL commands 192 can be issued immediately. If the thread's current context is made 193 current to another drawable, or if the thread makes another context 194 current on another drawable, rendering can proceed immediately. 195 196 If there are multiple outstanding swaps for the same window, at most 197 one such swap can be satisfied per increment of MSC. The order of 198 satisfying outstanding swaps of a window must be the order they were 199 issued. Each window that has an outstanding swap satisfied by the same 200 current MSC should have one swap done. 201 202 If a thread issues a glXSwapBuffersMscOML call on a window, then 203 issues OpenGL commands while still current to this window (which now 204 has a pending glXSwapBuffersMscOML call), the commands will be executed 205 in the order they were received, subject to implementation resource 206 constraints. Furthermore, subsequent commands that would affect 207 the back buffer will only affect the new back buffer (that is, the 208 back buffer after the swap completes). Such commands do not affect 209 the current front buffer. 210 211 If the graphics driver utilizes an extra thread to perform the wait, 212 it is expected that this thread will have a high priority so that 213 the swap will occur at the earliest possible moment once all the 214 conditions for swapping have been satisfied. 215 216 glXSwapBuffersMscOML will return the value that will correspond to 217 the value of the SBC when the buffer swap actually occurs (in other 218 words, the return value will be the current value of the SBC + the 219 number of pending buffer swaps + 1). It will return a value of -1 220 if the function failed because of errors detected in the input 221 parameters. glXSwapBuffersMscOML is a no-op and will always return 222 0 if the specified drawable was created with a non-double-buffered 223 GLXFBConfig or if the specified drawable is a GLXPixmap. 224 225 glXWaitForMscOML can be used to cause the calling thread to wait 226 until a specific graphics MSC value has been reached. If the current 227 MSC is less than the <target_msc> parameter for glXWaitForMscOML, 228 glXWaitForMscOML will block until the MSC value becomes equal to 229 <target_msc> and then will return the current values for UST, MSC, 230 and SBC. Otherwise, the function will block until the MSC value is 231 incremented to a value such that MSC % <divisor> = <remainder> and 232 then will return the current values for UST, MSC, and SBC. If 233 <divisor> = 0, then the wait will return as soon as MSC >= <target_msc>. 234 235 glXWaitForSbcOML can be used to cause the calling thread to wait 236 until a specific SBC value has been reached. This function will block 237 until the SBC value for <hdc> becomes equal to <target_sbc> and then 238 will return the current values for UST, MSC, and SBC. If the SBC 239 value is already greater than or equal to <target_sbc>, the function 240 will return immediately with the current values for UST, MSC, and 241 SBC. If <target_sbc> = 0, the function will block until all previous 242 swaps requested with glXSwapBuffersMscOML for that window have 243 completed. It will then return the current values for UST, MSC, 244 and SBC. 245 246 When glXSwapBuffersMscOML has been called to cause a swap at a 247 particular MSC, an application process would observe the following 248 order of execution for that MSC: 249 250 1. The window for which a glXSwapBuffersMscOML call has been 251 issued has been completely scanned out to the display for 252 the previous MSC 253 2. The swap buffer action for that window begins 254 3. All the swap buffer actions for all the windows for the 255 application process are completed 256 4. SBC and MSC values are atomically incremented 257 5. Any calls to glXWaitForMscOML or glXWaitForSbcOML that 258 are satisfied by the new values for SBC and graphics 259 MSC are released 260 261 The functions glXGetSyncValuesOML, glXGetMscRateOML, glXWaitForMscOML, 262 and glXWaitForSbcOML will each return TRUE if the function completed 263 successfully, FALSE otherwise. 264 265Errors 266 267 Each of the functions defined by this extension will generate a 268 GLX_BAD_CONTEXT error if there is no current GLXContext. 269 270 glXWaitForMscOML and glXWaitForSbcOML will each generate a 271 GLX_BAD_CONTEXT error if the current context is not direct. 272 273 glXSwapBuffersMscOML and glXWaitForMscOML will each generate 274 a GLX_BAD_VALUE error if <divisor> is less than zero, or if 275 <remainder> is less than zero, or if <remainder> is greater 276 than or equal to a non-zero <divisor>, or if <target_msc> is 277 less than zero. 278 279 glXWaitForSbcOML will generate a GLX_BAD_VALUE error if 280 <target_sbc> is less than zero. 281 282GLX Protocol 283 284 TBD 285 286New State 287 288 Get Value Get Command Type Initial Value 289 --------- ----------- ---- ------------- 290 [UST] glXGetSyncValuesOML Z unspecified 291 [MSC] glXGetSyncValuesOML Z 0 292 [SBC] glXGetSyncValuesOML Z 0 293 294New Implementation Dependent State 295 296 None 297 298 299 300 301 302 303 304 305